Webhooks
Cadastrar URL de webhook
Até 10 URLs ativas por empresa. Só https://, host público (IP privado, localhost e afins são
recusados com 422 WEBHOOK_URL_INVALID). O secret pra validar a assinatura aparece só
nesta resposta.
AuthorizationBearer <token>
Chave de API da sua empresa. Por enquanto a SwitchPay gera a chave e entrega à sua empresa; em breve será possível criar pelo painel.
In: header
Header Parameters
Idempotency-Key?string
Chave de idempotência. Opcional nesta rota.
Length
length <= 255urlstring
HTTPS obrigatório, host público
Format
uriLength
length <= 2048eventsarray<EventType>
Items
1 <= itemsdescription?string
Length
length <= 255Response Body
curl -X POST "https://api.sandbox.switchpay.app.br/v2/webhooks" \ -H "Idempotency-Key: string" \ -H "Content-Type: application/json" \ -d '{ "url": "https://integracao.parceiro.com.br/switchpay/webhook", "events": [ "transaction.created", "transaction.paid", "transaction.canceled" ], "description": "Produção — pedidos" }'{
"id": "whk_3a9d1b2c-4d5e-4f60-8a7b-9c0d1e2f3a4b",
"url": "https://integracao.parceiro.com.br/switchpay/webhook",
"events": [
"transaction.created",
"transaction.paid",
"transaction.canceled"
],
"description": "Produção — pedidos",
"secret": "whsec_9f8e7d6c5b4a39281706f5e4d3c2b1a0f9e8d7c6b5a4938271605f4e3d2c1b0a",
"active": true,
"createdAt": "2026-10-06T13:00:00.000Z"
}{
"code": "VALIDATION_ERROR",
"message": "Há campos inválidos na requisição.",
"details": [
{
"field": "url",
"message": "deve ser uma URL completa (https://...)"
}
]
}{
"code": "UNAUTHORIZED",
"message": "Chave de API ausente, inválida ou de outro ambiente."
}{
"code": "FORBIDDEN",
"message": "Sua chave não tem permissão para esta operação."
}{
"code": "WEBHOOK_URL_INVALID",
"message": "A URL precisa ser https:// e apontar para um host público.",
"details": [
{
"field": "url",
"message": "host resolve para IP privado"
}
]
}{
"code": "RATE_LIMITED",
"message": "Limite de chamadas atingido. Aguarde e tente de novo."
}{
"code": "SERVICE_UNAVAILABLE",
"message": "Serviço de autorização indisponível. Tente novamente em instantes."
}