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": [],
    "url": "https://empresa.com/empresa_webhook"
  }
}

Endpoints

Create Webhook Subscription

Establishes a new webhook subscription, configuring an HTTPS endpoint to receive notifications for specific event types.

Business Rules

The callback URL must be secured with HTTPS.
A maximum of 10 active webhook subscriptions are permitted per bank account.
Each unique combination of bank_account_id and endpoint_url must have only one active subscription.
At least one event type must be specified.

Subscription Categories (`event_types`)

These are the values you pass when creating a subscription:

Subscription	Description
`CASHIN.PIX.QRCODES`	Dynamic PIX QR codes created or paid via the API
`CASHIN.DEPOSITS`	Incoming PIX transfers to the account (excluding QR code payments)
`CASHOUT.PIX.TRANSFERS`	PIX transfer lifecycle (scheduled, completed, failed)
`CASHOUT.PIX.REFUNDS`	PIX refund completion or failure
`CASHOUT.BOLETO.PAYMENTS`	Boleto payment lifecycle (scheduled, completed, failed)
`CASHOUT.PIX.QRCODE.PAYMENTS`	Reserved — subscription accepted, no delivery yet

Delivery Event Types (`envelope.type`)

Each HTTP POST delivery uses a concrete event type in the envelope type field:

Subscription	Delivery events	Status
`CASHIN.PIX.QRCODES`	`CASHIN.PIX.QRCODES.CREATED`, `CASHIN.PIX.QRCODES.PAID`	Delivered
`CASHIN.DEPOSITS`	`CASHIN.DEPOSITS.RECEIVED`	Delivered
`CASHOUT.PIX.TRANSFERS`	`CASHOUT.PIX.TRANSFERS.SCHEDULED`, `CASHOUT.PIX.TRANSFERS.COMPLETED`, `CASHOUT.PIX.TRANSFERS.FAILED`, `CASHOUT.PIX.TRANSFERS.SCHEDULED.FAILED`	Delivered
`CASHOUT.PIX.TRANSFERS`	`CASHOUT.PIX.TRANSFERS.CREATED`	Planned
`CASHOUT.PIX.REFUNDS`	`CASHOUT.PIX.REFUNDS.COMPLETED`, `CASHOUT.PIX.REFUNDS.FAILED`	Delivered
`CASHOUT.BOLETO.PAYMENTS`	`CASHOUT.BOLETO.PAYMENTS.SCHEDULED`, `CASHOUT.BOLETO.PAYMENTS.COMPLETED`, `CASHOUT.BOLETO.PAYMENTS.FAILED`, `CASHOUT.BOLETO.PAYMENTS.SCHEDULED.FAILED`	Delivered
`CASHOUT.PIX.QRCODE.PAYMENTS`	—	Not implemented

For envelope format, payload shapes, HTTP headers, and signature verification, see the Receiving Webhooks guide pages.

POST

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": [],
    "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. At least one is required.

Event type to subscribe to for webhook notifications.

Each webhook subscription must include at least one event type. Events are sent as HTTP POST requests to the registered endpoint URL.

Subscription → delivery event mapping

Subscription	Delivery events (`envelope.type`)
`CASHIN.PIX.QRCODES`	`CASHIN.PIX.QRCODES.CREATED`, `CASHIN.PIX.QRCODES.PAID`
`CASHIN.DEPOSITS`	`CASHIN.DEPOSITS.RECEIVED`
`CASHOUT.PIX.TRANSFERS`	`CASHOUT.PIX.TRANSFERS.SCHEDULED`, `CASHOUT.PIX.TRANSFERS.COMPLETED`, `CASHOUT.PIX.TRANSFERS.FAILED`, `CASHOUT.PIX.TRANSFERS.SCHEDULED.FAILED` (planned: `CASHOUT.PIX.TRANSFERS.CREATED`)
`CASHOUT.PIX.REFUNDS`	`CASHOUT.PIX.REFUNDS.COMPLETED`, `CASHOUT.PIX.REFUNDS.FAILED`
`CASHOUT.BOLETO.PAYMENTS`	`CASHOUT.BOLETO.PAYMENTS.SCHEDULED`, `CASHOUT.BOLETO.PAYMENTS.COMPLETED`, `CASHOUT.BOLETO.PAYMENTS.FAILED`, `CASHOUT.BOLETO.PAYMENTS.SCHEDULED.FAILED`
`CASHOUT.PIX.QRCODE.PAYMENTS`	Reserved — no delivery yet

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.

Show child attributes

Boleto List Webhook Public Keys