Webhook

Um webhook é uma URL sua que a API chama via POST quando um evento assinado acontece — pagamento de cobrança Pix, devolução concluída ou pagamento de link de pagamento. Assim não é preciso consultar os recursos periodicamente (polling).

Modelo

Diferente de "uma URL por tipo", aqui cada webhook é um registro independente com sua própria URL, sua própria lista de eventos assinados e seu próprio secret de assinatura. Um mesmo cliente pode cadastrar quantos webhooks quiser — por exemplo, uma URL só para pix_charge.paid e outra para todos os eventos.

Eventos disponíveis

Esta página descreve o payload dos eventos Pix (pix_charge.paid e pix_refund.returned).

Cadastrar webhook

POST /api/v1/webhooks

Body

{
  "url": "https://meusistema.com.br/webhooks/pix",
  "events": ["pix_charge.paid", "pix_refund.returned"]
}

201 Created

{
  "id": "5bf69d18-c1d7-4348-adfe-6a4b28f2d4a1",
  "url": "https://meusistema.com.br/webhooks/pix",
  "events": ["pix_charge.paid", "pix_refund.returned"],
  "active": true,
  "createdAt": "2026-09-15T14:30:00Z",
  "secret": "2RMC_VPwUQ3nGQ5ywwpvIQPRkif3KWCIbCScJOP3nzY"
}

Erros: 400 URL inválida ou evento fora da lista · 401 certificado de cliente ausente ou inválido.

Atualizar webhook

PUT /api/v1/webhooks/{id}

Substitui URL, eventos assinados e o ativo/inativo de um webhook existente. O secret não muda e não é devolvido aqui.

Body

{
  "url": "https://meusistema.com.br/webhooks/pix",
  "events": ["pix_charge.paid"],
  "active": true
}

200 OK

{
  "id": "5bf69d18-c1d7-4348-adfe-6a4b28f2d4a1",
  "url": "https://meusistema.com.br/webhooks/pix",
  "events": ["pix_charge.paid"],
  "active": true,
  "createdAt": "2026-09-15T14:30:00Z"
}

Erros: 400 URL inválida ou evento fora da lista · 401 certificado de cliente ausente ou inválido · 404 webhook não encontrado para o cliente autenticado.

Listar webhooks

GET /api/v1/webhooks

Retorna todos os webhooks cadastrados para o cliente autenticado. O secret nunca aparece aqui — só na resposta de cadastro.

200 OK

[
  {
    "id": "5bf69d18-c1d7-4348-adfe-6a4b28f2d4a1",
    "url": "https://meusistema.com.br/webhooks/pix",
    "events": ["pix_charge.paid", "pix_refund.returned"],
    "active": true,
    "createdAt": "2026-09-15T14:30:00Z"
  }
]

Erros: 401 certificado de cliente ausente ou inválido.

Entrega do evento

Quando um evento assinado ocorre, a API enfileira uma entrega para cada webhook que o assina e um job de despacho tenta o POST em segundos — a requisição que gerou o evento (criar cobrança, solicitar devolução) não espera a entrega acontecer.

Corpo da entrega

{
  "event": "pix_charge.paid",
  "occurredAt": "2026-09-15T14:32:10.832351Z",
  "data": { }
}

Em pix_charge.paid, data é a cobrança no formato de Consultar cobrança. Em pix_refund.returned, data é a devolução no formato de Consultar devolução.

Headers enviados

Verificando a assinatura

X-Webhook-Signature é o HMAC-SHA256 do corpo cru da requisição (os bytes exatos recebidos, antes de qualquer parse), calculado com o secret devolvido no cadastro, em hexadecimal minúsculo.

signature = hex(HMAC_SHA256(secret, corpo_cru))

Recalcule esse valor no seu servidor e compare com o header antes de confiar no conteúdo da requisição.

Retentativas

Uma entrega só é considerada bem-sucedida com resposta 2xx. Qualquer outro status, erro de conexão ou timeout conta como falha e é reagendada com backoff:

Boas práticas

• Responda rápido com 2xx. Processe o evento de forma assíncrona no seu lado. Qualquer resposta fora da faixa 2xx é tratada como falha e entra no ciclo de retentativas acima.
• Valide a assinatura. Nunca processe o corpo sem antes conferir X-Webhook-Signature — ver Verificando a assinatura.
• Seja idempotente. O mesmo evento pode chegar mais de uma vez (retentativa após um 2xx que não chegou a tempo, por exemplo). Use X-Webhook-Delivery como chave para não processar em duplicidade.
• Confirme antes de liberar. Antes de entregar o produto ou serviço, confirme o status em Consultar cobrança.
• Use HTTPS na URL do webhook e não exponha dados sensíveis na query string.