Criar inscrição
Cadastra a URL que recebe os eventos da sua conta, escolhe os eventos e devolve o segredo da assinatura.
apiKeyAuthorizationBearer <token>Chave de API no header Authorization: Bearer <chave de API>.
application/json- body
subscribedEvents*array<>Eventos que a inscrição recebe. Pelo menos um. A API não recusa um nome fora do catálogo, mas nenhum evento com esse nome é entregue: confira a grafia.
1 <= itemscallbackUrl*CallbackUrlURL que recebe os eventos. http ou https, endereço público com
domínio de topo (.com, .com.br…), nas portas 80, 443, 8080 ou 8443.
IP privado ou reservado, localhost e usuário/senha na URL são
recusados. Use https em produção.
urilength <= 2048Inscrição criada. Contém o secret, exibido só desta vez.
application/json- response
Inscrição com o secret. Só nas respostas de Criar inscrição e Rotacionar segredo.
id*stringIdentificador da inscrição, em ULID.
ownerId*integerId da conta dona da inscrição. Vem da chave de API; não é enviado no corpo.
subscribedEvents*array<>Eventos que a inscrição recebe.
callbackUrl*stringURL que recebe os eventos.
uristatus*WebhookSubscriptionStatusactive: recebe eventos. paused: não recebe; volta com Ativar.
revoked: desligada.
"active""paused""revoked"failureCount*integerTentativas de entrega que falharam desde a última entrega com
sucesso. Conta cada nova tentativa, não cada evento; volta a 0 na
próxima entrega aceita.
lastFailureAt*|Data e hora (ISO 8601, UTC) da última falha de entrega, ou null.
date-timecreatedAt*stringData e hora de criação (ISO 8601, UTC).
date-timeupdatedAt*stringData e hora da última alteração (ISO 8601, UTC).
date-timesecret*stringSegredo da assinatura HMAC-SHA256, em texto puro (43 caracteres, base64url). Aparece só nesta resposta; guarde-o em um cofre de segredos. Se perder, rotacione.
curl -X POST 'https://api.gates2b.com/webhook-subscriptions' \ -H 'Content-Type: application/json' \ -d '{ "callbackUrl": "https://loja.example.com/webhooks/pagamentos", "subscribedEvents": [ "charge.paid", "charge.refunded", "payout.paid", "payout.failed" ]}'{ "id": "01KTQRHR29PZ588RB1YQZWS4A6", "ownerId": 314, "subscribedEvents": [ "charge.paid", "charge.refunded", "payout.paid", "payout.failed" ], "callbackUrl": "https://loja.example.com/webhooks/pagamentos", "status": "active", "failureCount": 0, "lastFailureAt": null, "createdAt": "2026-06-15T14:00:00.000Z", "updatedAt": "2026-06-15T14:00:00.000Z", "secret": "4QypFUhtII81w7FdxdkK7ob9wVVRH0dyOgumZkU2yqg"}O secret aparece só nesta resposta. Guarde-o em um cofre de segredos antes de qualquer outra coisa: ele valida
o header x-Webhook-Signature de cada entrega. Se perder, use Rotacionar segredo.
Regras
- A inscrição pertence à conta da chave de API. Um
ownerIdenviado no corpo é ignorado. - Só o dono ou um administrador da conta cria inscrições. Outros perfis recebem
403. - Cada conta pode ter uma única inscrição
activeporcallbackUrl. Repetir a URL responde409; para mudar os eventos, use Atualizar inscrição. - Para mandar eventos diferentes para URLs diferentes, crie uma inscrição por URL. Um evento assinado por duas inscrições é entregue às duas.
- A URL é validada no cadastro e de novo a cada entrega. Se, na entrega, ela apontar para um endereço proibido
(IP privado, por exemplo), a inscrição passa para
paused. - Os nomes em
subscribedEventssão exatos. Um nome com erro de grafia é aceito e nunca recebe nada.
Antes de criar a inscrição, prepare o endpoint para validar a assinatura. Veja Webhooks.