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.

Each webhook subscription can listen to multiple event types. Events are sent as HTTP POST requests to the registered endpoint URL.

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.