Webhooks
Webhooks avisam o seu servidor, em tempo real, quando algo muda: uma cobrança foi paga, uma devolução terminou, um repasse foi realizado, uma assinatura foi autorizada. Você não precisa ficar consultando a API.
Configurando
No painel, em Integração → Webhooks:
- ligue Enviar webhooks;
- informe a URL do seu servidor;
- (recomendado) ligue Assinar com HMAC e valide a assinatura;
- clique em Enviar teste para receber um evento
ping.
A URL precisa:
- usar HTTPS;
- apontar para um endereço público da internet (endereços internos,
localhoste IPs privados são recusados); - não conter usuário e senha.
Nota
A URL é validada ao salvar e de novo a cada envio. Se o seu domínio passar a apontar para um endereço interno, o envio é bloqueado.
A requisição
A marx faz um POST com corpo JSON:
HTTP
POST /webhooks/marx HTTP/1.1
Content-Type: application/json
X-Webhook-Event: event_type_charge
X-Marx-Event-Id: 9a7c3e1b-5d2f-4c8a-b6e0-1f2d3c4b5a69
X-Reference: pedido-1001
X-Marx-Timestamp: 1759769002
X-Marx-Signature: t=1759769002,v1=5f2b0c…e1c9
{
"event": "event_type_charge",
"payload": { … },
"original_payload": { … }
}
| Cabeçalho | Descrição |
|---|---|
X-Webhook-Event |
Tipo do evento (igual a event). |
X-Marx-Event-Id |
ID único do evento. Use para descartar duplicados. Reenvios do mesmo evento mantêm o ID. |
X-Reference |
O seu reference do recurso, quando existir. |
X-Marx-Timestamp / X-Marx-Signature |
Assinatura HMAC, quando ativada. Veja Validar assinatura. |
User-Agent |
Começa com marx-. |
O corpo tem três campos:
| Campo | Descrição |
|---|---|
event |
Tipo do evento. |
payload |
O recurso no formato da marx (documentado abaixo). Use este. |
original_payload |
Dados brutos da rede de pagamentos, para auditoria. O formato pode mudar sem aviso: não dependa dele. |
Importante
Empresas antigas podem estar no formato legado (v1), em que o corpo é apenas o dado bruto da rede de pagamentos, sem event e payload. O formato de cada empresa aparece no painel ("payload v1/v2"). Novas integrações devem usar o v2; peça a migração ao time marx.
Eventos
event |
Quando é enviado | payload |
|---|---|---|
event_type_charge |
Cobrança paga ou com status alterado; devolução concluída ou falha (com o objeto refund). |
Cobrança |
event_type_payout |
Repasse realizado ou não realizado. | Repasse |
event_type_pix_automatico_subscription |
Assinatura autorizada, recusada, expirada ou cancelada. | Assinatura |
event_type_pix_automatico_charge |
Cobrança do ciclo paga, falha, expirada, cancelada ou devolvida. | Cobrança do ciclo |
event_type_med |
Infração MED aberta ou com status alterado, ou defesa enviada. | Infração |
event_type_nfse_authorized |
NFS-e autorizada (beta, sob liberação). | Nota fiscal |
event_type_nfse_rejected |
NFS-e recusada; errors traz os códigos. |
Nota fiscal |
event_type_nfse_cancelled |
Cancelamento de NFS-e registrado. | Nota fiscal |
event_type_nfse_replaced |
NFS-e substituída (enviado para a nota original). | Nota fiscal |
event_type_nfse_cancellation_rejected |
Cancelamento de NFS-e recusado pelo Ambiente Nacional. | Nota fiscal |
event_type_nfse_needs_data |
NFS-e automática aguardando o CPF/CNPJ do tomador. | Nota fiscal |
ping |
Botão Enviar teste do painel. | { "event": "ping", "sent_at": "…" } |
Cobrança paga
JSON
{
"event": "event_type_charge",
"payload": {
"pix_txid": "0f6e2a3c7c1d4f439b2f5e8d9a4b1c22",
"reference": "pedido-1001",
"amount": "149.9",
"amount_system": "2.25",
"amount_to_pay": "147.65",
"pix_status": "CONCLUIDA",
"lifecycle_status": "settled",
"pix_endtoend": "E0000000020261006170312345678901",
"pix_payer_name": "MARIA SOUZA",
"pix_created_at": "2026-10-06T14:03:22-03:00",
"pix_payed_at": "2026-10-06T14:05:47-03:00",
"metadata": { "customer_id": "c_871" },
"refunds": []
},
"original_payload": { }
}
Identifique a cobrança por pix_txid ou pelo seu reference.
Devolução concluída
JSON
{
"event": "event_type_charge",
"payload": {
"pix_txid": "0f6e2a3c7c1d4f439b2f5e8d9a4b1c22",
"reference": "pedido-1001",
"pix_status": "DEVOLVIDO",
"lifecycle_status": "reversed",
"refund": { "refund_id": "DEV1001A", "amount": "50.0", "status": "DEVOLVIDO", "lifecycle_status": "reversed",
"confirmed_at": "2026-10-06T15:12:40-03:00" },
"refunds": [ { "refund_id": "DEV1001A", "amount": "50.0", "status": "DEVOLVIDO", "lifecycle_status": "reversed" } ]
}
}
Repasse realizado
JSON
{
"event": "event_type_payout",
"payload": {
"id": "4a5d2c8e-91b7-4f0a-8e3c-6d1b2a9f7e40",
"reference": "comissao-2026-10-parceiro-12",
"amount_payout": "250.0",
"pix_status": "REALIZADO",
"lifecycle_status": "settled",
"pix_endtoend": "E1234567820261006171512345678901",
"paid_at": "2026-10-06T17:15:19-03:00",
"metadata": { "partner_id": "p_12" }
}
}
Respondendo
- Responda
2xxem até 5 segundos. Qualquer outro status, ou demora, conta como falha. - Valide a assinatura, grave o evento e processe depois (fila), em vez de processar dentro da requisição.
- Redirecionamentos (
3xx) não são seguidos.
Novas tentativas
Se a entrega falhar, a marx tenta de novo após 30 s, 2 min, 10 min, 30 min e 2 h (6 tentativas em cerca de 3 horas). Depois disso o evento fica marcado como falho no painel (Webhooks), de onde você pode reenviar quando o seu servidor voltar.
Boas práticas
- Idempotência: o mesmo evento pode chegar mais de uma vez (novas tentativas, reenvios manuais) e uma cobrança pode gerar mais de um evento com o mesmo status. Guarde
X-Marx-Event-Ide baseie a lógica no status atual (lifecycle_status), não na contagem de eventos. - Ordem: eventos podem chegar fora de ordem. Compare horários (
pix_payed_at,paid_at) ou consulte a API antes de regredir um status. - Campos novos: ignore campos que você não conhece; podemos adicionar campos sem aviso.
- Conciliação: se um evento não chegar, consulte o recurso pela API (cobrança por
pix_txid, repasse porid).