Webhooks

Como funciona

1. 1
   Cadastre o webhook

   Cadastre no painel de webhooks ou por POST /webhooks, com a URL do seu servidor e os eventos que quer receber. Sua conta precisa ter uma chave de API ativa. A URL precisa começar com https:// e usar um domínio público que já exista no DNS: endereços IP e URLs com usuário ou senha são recusados com INVALID_INPUT.

2. 2
   Guarde o segredo de assinatura

   Ele vem na resposta da criação, no formato whsec_…, e pode ser consultado de novo com GET /webhooks/{id}?include_signing_secret=true. Não há como gerar outro: se vazar, exclua o webhook e crie um novo. Não confunda com a chave de API.

3. 3
   Receba o POST

   Cada evento chega num POST, com o JSON do evento no corpo e os cabeçalhos svix-id, svix-timestamp e svix-signature.

4. 4
   Valide, grave e responda 2xx

   Confira a assinatura, grave o evento e só então responda. Qualquer resposta fora de 2xx, ou a falta de resposta, gera novas tentativas.

Eventos

Cada evento traz type, que diz o que aconteceu, e related_object: o type do objeto (order, refund ou webhook), o id e a url, caminho da consulta em https://bytemax.exchange. Para agir, consulte essa url: a consulta sempre devolve o estado atual, mesmo que o evento chegue atrasado, repetido ou fora de ordem.

{
  "id": "evt_example",
  "type": "order.completed",
  "created_at": "2026-09-10T13:05:00.000Z",
  "related_object": {
    "type": "order",
    "id": "ord_example",
    "url": "/api/v1/orders/ord_example"
  }
}

Estados de publicação

GET /events e GET /events/{id} trazem publication_status, que diz se o evento saiu da ByteMax. O resultado no seu servidor fica nas entregas.

pending

Registrado e aguardando o envio, ou em nova tentativa. A ByteMax tenta publicar por cerca de 2 horas; depois disso, o evento fica not_published.

published

Enviado para entrega. O resultado de cada tentativa fica nas entregas.

not_published

Não enviado: sua conta estava sem chave de API ativa, nenhum dos seus webhooks ativos assinava esse tipo de evento naquele momento, ou a publicação falhou. Não pode ser reenviado; consulte a ordem ou o reembolso para ver o estado atual.

Receber e verificar

Valide com o segredo e o corpo bruto da requisição, antes de interpretar o JSON. Use a biblioteca oficial do Svix na sua linguagem: ela confere a assinatura e a tolerância de tempo do svix-timestamp. Não implemente a verificação à mão.

Como verificar assinaturas com a biblioteca oficial (docs.svix.com)

POST /webhooks/bytemax HTTP/1.1
Content-Type: application/json
svix-id: msg_2gkQ7Wc9cD6yYq1xkKz7GJb3wQm
svix-timestamp: 1789045500
svix-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhUjM8G3xRk2w1vNq4T0=

{ "id": "evt_example", "type": "order.completed", ... }

Processar sem duplicar

Eventos podem chegar mais de uma vez e fora de ordem. Cinco regras evitam efeitos duplicados:

• Use o id do evento como chave única: grave antes de responder e ignore repetidos.
• Não dependa da ordem de chegada: a cada evento, consulte a ordem ou o reembolso e aja pelo estado que a consulta devolver.
• Grave o efeito do evento e a marca de processado na mesma transação.
• Responda 2xx só depois de gravar. Se a gravação falhar, responda 5xx para receber de novo.
• Trabalho demorado fica fora da resposta: enfileire e responda rápido.

Testar e reenviar

POST /webhooks/{id}/test-events com Content-Type: application/json e {} no corpo envia um webhook.test para esse webhook, que precisa estar ativo. Acompanhe a publicação em GET /events/{id} e confira no seu servidor se o evento chegou e a assinatura foi aceita. O teste comprova a entrega e a assinatura; para testar o tratamento de ordens e reembolsos, acompanhe uma ordem real.

Entregas que falham recebem até 7 novas tentativas automáticas: depois de 5 segundos, 5 minutos, 30 minutos, 2 horas, 5 horas, 10 horas e 10 horas. Um webhook que falha sem parar por 5 dias é desativado automaticamente. O histórico de cada tentativa fica no painel e em GET /webhooks/{id}/deliveries. Para reenviar eventos específicos, use POST /webhooks/{id}/redeliveries com até 100 IDs. A chamada responde 200 mesmo quando alguns eventos são recusados: leia o status de cada item.

queued

O reenvio foi aceito.

rejected

Nada foi reenviado. O code diz o motivo: EVENT_NOT_FOUND (o ID não existe), EVENT_NOT_ACCEPTED (o webhook não assina esse tipo de evento, ou o teste é de outro webhook), EVENT_NOT_PUBLISHED (o evento ainda está pending ou ficou not_published) ou REDELIVERY_REJECTED (o serviço de entregas recusou). Um evento pending pode ser reenviado quando GET /events/{id} mostrar published.

retry

O reenvio não foi feito ou não pôde ser confirmado: o tempo da chamada acabou, o serviço de entregas estava ocupado ou falhou. Envie de novo; se o evento chegar duas vezes, o id dele evita efeito duplicado.

Limites

• Até 200 webhooks por conta, um por URL.
• Eventos ficam consultáveis por 30 dias depois da publicação.
• Listas usam items e next_cursor: 30 por página, no máximo 100. Um cursor só vale na mesma lista e com os mesmos filtros.

Erros

Autenticação, erros gerais e limite de chamadas estão na página da API. Estes códigos são próprios dos webhooks:

WEBHOOK_URL_EXISTSHTTP 409

Você já tem um webhook com esta URL.

WEBHOOK_LIMIT_REACHEDHTTP 409

Você já tem 200 webhooks. Exclua um antes de criar outro.

WEBHOOK_NOT_ENABLED_FOR_V1HTTP 409

Testes e reenvios exigem um webhook ativo e na v1. Ative o webhook ou, se ele veio da API anterior, migre-o para a v1 com PATCH.

WEBHOOK_VERSION_REQUIREDHTTP 400

Um webhook da API anterior só pode ser alterado junto com a migração para a v1: envie api_version: "v1" e os novos events.

WEBHOOK_NOT_FOUNDHTTP 404

Não há webhook com este ID na sua conta.

EVENT_NOT_FOUNDHTTP 404

Não há evento com este ID. Eventos ficam guardados por 30 dias depois da publicação.

INVALID_CURSORHTTP 400

O cursor não pertence a esta lista com estes filtros. Recomece sem cursor.

Uma resposta 503 SERVICE_UNAVAILABLE indica que o serviço de entregas está temporariamente indisponível. Repita depois de alguns segundos.

Referência

Dez operações, todas com Authorization: Bearer <API_KEY>. As três mais usadas aparecem completas; as demais seguem o mesmo formato.

curl --request POST "https://bytemax.exchange/api/v1/webhooks" \
  --header "Authorization: Bearer <API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{"url":"https://merchant.example/webhooks/bytemax","events":["order.created","order.completed","order.expired","order.canceled","order.updated","refund.created","refund.succeeded","refund.failed"],"enabled":true}'

{
  "id": "ep_example",
  "url": "https://merchant.example/webhooks/bytemax",
  "events": [
    "order.created",
    "order.completed",
    "order.expired",
    "order.canceled",
    "order.updated",
    "refund.created",
    "refund.succeeded",
    "refund.failed"
  ],
  "enabled": true,
  "api_version": "v1",
  "signing_secret": "<WEBHOOK_SIGNING_SECRET>"
}

curl --request POST "https://bytemax.exchange/api/v1/webhooks/ep_example/test-events" \
  --header "Authorization: Bearer <API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{}'

{
  "id": "evt_test_example",
  "type": "webhook.test",
  "created_at": "2026-09-10T13:05:00.000Z",
  "related_object": {
    "type": "webhook",
    "id": "ep_example",
    "url": "/api/v1/webhooks/ep_example"
  },
  "publication_status": "pending"
}

curl --request POST "https://bytemax.exchange/api/v1/webhooks/ep_example/redeliveries" \
  --header "Authorization: Bearer <API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{"event_ids":["evt_example"]}'

{
  "items": [
    {
      "event_id": "evt_example",
      "status": "queued"
    }
  ]
}