Eventos
Webhooks
A Mainum faz um POST no seu endpoint a cada mudança importante. Todo evento traz o recurso completo em data.object, no mesmo formato da consulta.
Confira a assinatura antes de confiar no evento. Calcule o HMAC-SHA256 de
timestamp.corpo com o segredo do endpoint e compare com X-Mainum-Signature. Responda 2xx em até 5 segundos; sem isso, fazemos até 8 tentativas, com esperas de 1 min, 5 min, 15 min, 1 h, 3 h, 6 h e 12 h (cerca de 22 horas no total). Se 5 eventos seguidos se esgotarem sem sucesso, o endpoint é desativado e a conta recebe um aviso por e-mail; cadastre a URL de novo depois de corrigir o servidor.Verificação do endpoint. Ao cadastrar uma URL, enviamos um
POST assinado com o evento webhook_endpoint.verification e data.endpoint_id. Aceitamos resposta 2xx ou 400, 401, 403 e 422 (seu servidor ainda não conhece o segredo); 404, 405, 410, 501, redirecionamento ou tempo esgotado recusam o cadastro.Catálogo
Cabeçalhos de cada entrega
| Cabeçalho | Conteúdo |
|---|---|
X-Mainum-Event-Id | ID único do evento, igual ao de GET /v1/events. Use para ignorar entregas repetidas. |
X-Mainum-Timestamp | Segundos desde 1970. Rejeite entregas com mais de 5 minutos. |
X-Mainum-Signature | v1= seguido do HMAC-SHA256 em hexadecimal. |
Boas práticas
- Leia o corpo cru antes de converter para JSON; a assinatura vale sobre os bytes exatos.
- Os eventos podem chegar fora de ordem ou repetidos. Use
data.object.statuse o ID do evento, não a ordem de chegada. - Os campos fora de
data.objectexistem por compatibilidade; neles os centavos vêm como texto. - Perdeu alguma entrega? Recupere pela lista de eventos com
created_from.