Skip to main content
POST
/
v1
/
webhooks
Create Webhook Subscription
curl --request POST \
  --url https://conta-public-api.kiwify.com/v1/webhooks \
  --header 'Content-Type: application/json' \
  --header 'X-PoP-Challenge: <api-key>' \
  --header 'X-PoP-Format: <api-key>' \
  --header 'X-PoP-Signature: <api-key>' \
  --header 'x-access-id: <api-key>' \
  --data '
{
  "event_types": [
    "CASHIN.PIX.QRCODES",
    "CASHIN.DEPOSITS"
  ],
  "url": "https://empresa.com/empresa_webhook"
}
'
{
  "message": "Webhook successfully created",
  "webhook": {
    "id": "6225875037061120",
    "subscriptions": [
      "CASHIN.PIX.QRCODES"
    ],
    "url": "https://empresa.com/empresa_webhook"
  }
}

Authorizations

​
x-access-id
string
header
required

UUID of the service account (e.g., 550e8400-e29b-41d4-a716-446655440000)

​
X-PoP-Challenge
string
header
required

Unix timestamp in milliseconds (e.g., 1704636800000). Must be within 5 minutes of server time.

​
X-PoP-Format
string
header
required

Must be 'service-account' for service account authentication

​
X-PoP-Signature
string
header
required

EdDSA signature of the request in base64 format. Signs: uri:method:body:timestamp

Body

application/json

Request body for creating a webhook subscription.

​
event_types
enum<string>[]
required

List of event types to subscribe to. Must contain between 1 and 6 event types.

Event type to subscribe to for webhook notifications.

Available options:
CASHIN.PIX.QRCODES,
CASHIN.DEPOSITS,
CASHOUT.PIX.TRANSFERS,
CASHOUT.PIX.REFUNDS,
CASHOUT.BOLETO.PAYMENTS,
CASHOUT.PIX.QRCODE.PAYMENTS
Example:
["CASHIN.PIX.QRCODES", "CASHIN.DEPOSITS"]
​
url
string
required

HTTPS endpoint URL that will receive webhook event notifications. Must be a valid HTTPS URL with a maximum length of 2048 characters.

Example:

"https://empresa.com/empresa_webhook"

Response

Webhook subscription created successfully

Response returned after successfully creating a webhook subscription.

​
message
string
required

Human-readable confirmation message.

Example:

"Webhook successfully created"

​
webhook
object
required

The newly created webhook subscription.