Criar Assinatura de Webhook

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

Criar Assinatura de Webhook

O endpoint HTTPS fornecido receberá notificações de eventos para os tipos de evento especificados.

Regras de Negócio

A URL do endpoint deve usar HTTPS.
Uma conta bancária pode ter no máximo 10 assinaturas de webhook ativas.
Cada combinação (bank_account, endpoint_url) deve ser única entre as assinaturas ativas.
Pelo menos um tipo de evento deve ser especificado.

Categorias de Assinatura (`event_types`)

Valores aceitos ao criar uma assinatura:

Assinatura	Descrição
`CASHIN.PIX.QRCODES`	QR codes PIX dinâmicos criados ou pagos via API
`CASHIN.DEPOSITS`	Transferências PIX recebidas na conta (excluindo pagamentos via QR code)
`CASHOUT.PIX.TRANSFERS`	Ciclo de vida de transferências PIX (agendadas, concluídas, falhas)
`CASHOUT.PIX.REFUNDS`	Conclusão ou falha de estornos PIX
`CASHOUT.BOLETO.PAYMENTS`	Ciclo de vida de pagamentos de boleto (agendados, concluídos, falhas)
`CASHOUT.PIX.QRCODE.PAYMENTS`	Reservado — assinatura aceita, sem entrega ainda

Tipos de Evento de Entrega (`envelope.type`)

Cada entrega HTTP POST usa um tipo concreto no campo type do envelope:

Assinatura	Eventos de entrega	Status
`CASHIN.PIX.QRCODES`	`CASHIN.PIX.QRCODES.CREATED`, `CASHIN.PIX.QRCODES.PAID`	Entregue
`CASHIN.DEPOSITS`	`CASHIN.DEPOSITS.RECEIVED`	Entregue
`CASHOUT.PIX.TRANSFERS`	`CASHOUT.PIX.TRANSFERS.SCHEDULED`, `CASHOUT.PIX.TRANSFERS.COMPLETED`, `CASHOUT.PIX.TRANSFERS.FAILED`, `CASHOUT.PIX.TRANSFERS.SCHEDULED.FAILED`	Entregue
`CASHOUT.PIX.TRANSFERS`	`CASHOUT.PIX.TRANSFERS.CREATED`	Planejado
`CASHOUT.PIX.REFUNDS`	`CASHOUT.PIX.REFUNDS.COMPLETED`, `CASHOUT.PIX.REFUNDS.FAILED`	Entregue
`CASHOUT.BOLETO.PAYMENTS`	`CASHOUT.BOLETO.PAYMENTS.SCHEDULED`, `CASHOUT.BOLETO.PAYMENTS.COMPLETED`, `CASHOUT.BOLETO.PAYMENTS.FAILED`, `CASHOUT.BOLETO.PAYMENTS.SCHEDULED.FAILED`	Entregue
`CASHOUT.PIX.QRCODE.PAYMENTS`	—	Não implementado

Para formato do envelope, estruturas de payload, headers HTTP e verificação de assinatura, consulte as páginas Recebendo Webhooks.

POST

webhooks

Criar Assinatura de Webhook

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"
  }
}

Autorizações

x-access-id

string

header

obrigatório

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

X-PoP-Challenge

string

header

obrigatório

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

X-PoP-Format

string

header

obrigatório

Must be 'service-account' for service account authentication

X-PoP-Signature

string

header

obrigatório

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

Corpo

application/json

Request body for creating a webhook subscription.

event_types

enum<string>[]

obrigatório

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

Opções disponíveis:

CASHIN.PIX.QRCODES,

CASHIN.DEPOSITS,

CASHOUT.PIX.TRANSFERS,

CASHOUT.PIX.REFUNDS,

CASHOUT.BOLETO.PAYMENTS,

CASHOUT.PIX.QRCODE.PAYMENTS

Exemplo:

["CASHIN.PIX.QRCODES", "CASHIN.DEPOSITS"]

url

string

obrigatório

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

Exemplo:

"https://empresa.com/empresa_webhook"

Resposta

Webhook subscription created successfully

Response returned after successfully creating a webhook subscription.

message

string

obrigatório

Human-readable confirmation message.

Exemplo:

"Webhook successfully created"

webhook

object

obrigatório

The newly created webhook subscription.

Show child attributes

Boleto Listar Chaves Públicas de Webhook