Webhooks

Webhooks entregam os Eventos do Repass aos seus servidores por HTTP, em tempo real. Você assina um subconjunto da taxonomia de eventos por endpoint, e o Repass faz POST no seu endpoint sempre que um desses eventos acontece: afiliado aprovado, conversão registrada, comissão paga, payout concluído, e assim por diante. Cada evento assinado vira uma entrega assinada com HMAC, com retry exponencial e dead letter em caso de falha. O corpo entregue tem exatamente o mesmo shape do GET /events/{id}, então tudo o que você recebe via webhook também é consultável pela API.

Webhooks são o canal de push; o GET /events é o canal de pull. Use os dois em conjunto: o webhook avisa em tempo real e a API permite recuperar qualquer evento perdido. A entrega é at-least-once: deduplique pelo id do evento (veja Assinatura).

Criar um endpoint

Crie um endpoint com POST /webhook-endpoints, informando a url de destino e a lista de tipos de evento que quer receber (subscribedEvents). A lista é validada contra a taxonomia da plataforma: um tipo desconhecido é rejeitado com 400 parameter_invalid.

string

required

URL HTTPS que receberá as entregas (POST).

string[]

required

Tipos de evento assinados. No mínimo 1 elemento, todos validados contra o catálogo de eventos. O tipo sintético webhook.test não pode ser assinado.

string

Texto livre opcional (máx. 500 caracteres).

curl https://api.userepass.com/webhook-endpoints \
  -H "Authorization: Bearer rstr_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: c0ffee00-0000-4000-8000-000000000001" \
  -d '{
    "url": "https://app.exemplo.com.br/hooks/repass",
    "description": "Producao",
    "subscribedEvents": [
      "conversion.created",
      "commission.approved",
      "commission.paid",
      "payout.completed"
    ]
  }'

A resposta 201 inclui o campo secret em claro: esta é a única vez que ele aparece em texto puro. Guarde-o de forma segura; em qualquer outra response ou evento o segredo vem apenas mascarado, no campo maskedSecret (rwhs_***<últimos 4>).

{
  "id": "whep_01HZX9QK7M3R8V4N2P6T0YBC5D",
  "url": "https://app.exemplo.com.br/hooks/repass",
  "description": "Producao",
  "subscribedEvents": [
    "conversion.created",
    "commission.approved",
    "commission.paid",
    "payout.completed"
  ],
  "status": "active",
  "disabledReason": null,
  "maskedSecret": "rwhs_***NyZXQ",
  "secret": "rwhs_dGhpc19pc19hX3JhbmRvbV9zZWNyZXQ",
  "previousSecretExpiresAt": null,
  "createdAt": "2026-06-13T12:00:00.000Z"
}

O secret aparece em claro apenas na resposta do create e do rotate-secret. Se você o perder, rode rotate-secret para gerar um novo. Use o secret para validar a assinatura HMAC de cada entrega. Veja Assinatura.

Um endpoint recém-criado não recebe histórico: ele só passa a receber eventos que acontecem a partir da sua criação. Para recuperar eventos anteriores, use o GET /events.

Payload entregue

Cada entrega é um POST cujo corpo é o envelope do evento, o mesmo shape retornado por GET /events/{id}. A entrega também carrega os headers Repass-Signature (assinatura HMAC) e content-type: application/json.

string

ID do evento (evt_<ULID>). Use-o para deduplicar entregas repetidas.

string

ID da organização dona do evento (org_...).

string

Tipo namespaced recurso.ação (ex.: commission.paid). Veja o catálogo de eventos.

integer

Versão do schema do payload daquele tipo. Hoje todos os tipos estão em version: 1.

string

Agregado a que o evento se refere (ex.: commission).

string

ID do agregado (ex.: comm_...).

object

Snapshot do fato: diff, entidade completa ou campos específicos, conforme o tipo. Dinheiro em centavos (inteiro), percentuais em basis points.

object

{ actor: { type, id }, source? }, onde actor.type é user, api_key ou system.

string

Quando o fato ocorreu (ISO-8601).

string

Quando o evento foi gravado no store (ISO-8601).

{
  "id": "evt_01HZXB2M9P4Q7R5S3T8V0WCD6E",
  "organizationId": "org_01HZX7VN4F2J8K0M3P5R7TBC2D",
  "type": "commission.paid",
  "version": 1,
  "aggregateType": "commission",
  "aggregateId": "comm_01HZXAYR2K8M4N6P0Q3T5VBC9D",
  "payload": {
    "affiliateId": "aff_01HZX8WP5J3K7M9N2Q4R6TBC0D",
    "amountCents": 12500,
    "payoutId": "pay_01HZXBQ7N4P2R6S8T0V3WCD5E"
  },
  "metadata": {
    "actor": { "type": "system", "id": "payout-cycle" }
  },
  "occurredAt": "2026-06-13T11:59:58.000Z",
  "recordedAt": "2026-06-13T11:59:58.412Z"
}

Responda com 2xx para confirmar o recebimento. Qualquer outra resposta (ou timeout de 10s) é tratada como falha e dispara o retry. Veja Retries e dead letter.

Gerenciar endpoints

Listar
Detalhar
Atualizar
Remover

GET /webhook-endpoints lista os endpoints da organização, paginado por cursor ULID em ordem decrescente. Secrets sempre mascarados.

curl https://api.userepass.com/webhook-endpoints?limit=25 \
  -H "Authorization: Bearer rstr_..."

GET /webhook-endpoints/{endpointId} retorna um endpoint (secret mascarado).

curl https://api.userepass.com/webhook-endpoints/whep_01HZX9QK7M3R8V4N2P6T0YBC5D \
  -H "Authorization: Bearer rstr_..."

PATCH /webhook-endpoints/{endpointId} altera url, description, subscribedEvents ou status. Para desativar manualmente, envie status: "disabled"; para reativar, status: "active" (limpa o disabledReason).

curl -X PATCH https://api.userepass.com/webhook-endpoints/whep_01HZX9QK7M3R8V4N2P6T0YBC5D \
  -H "Authorization: Bearer rstr_..." \
  -H "Content-Type: application/json" \
  -d '{ "subscribedEvents": ["conversion.created", "conversion.refunded"] }'

DELETE /webhook-endpoints/{endpointId} faz hard delete e apaga o log de entregas junto (204).

curl -X DELETE https://api.userepass.com/webhook-endpoints/whep_01HZX9QK7M3R8V4N2P6T0YBC5D \
  -H "Authorization: Bearer rstr_..."

Todas as rotas são autenticadas (sessão ou API key Authorization: Bearer rstr_...) e escopadas pela sua organização. Um endpoint de outra organização retorna 404, não 403. Para a referência completa de campos e respostas, veja a aba Referência da API.

Ciclo de vida do endpoint

active (inicial): recebe eventos e tentativas de entrega.
disabled: não recebe novos eventos; entregas em curso encerram sem retry e replay é recusado com 409 conflict. O disabledReason registra a causa: manual (via PATCH) ou failure_rate (auto-desativação). Veja Retries e dead letter para a regra de auto-desativação.

Rotacionar o secret

POST /webhook-endpoints/{endpointId}/rotate-secret gera um novo secret, retém o anterior e define uma graça de 24h (devolvida em previousSecretExpiresAt). Durante a graça, cada entrega é assinada com os dois secrets (dois v1=, o novo primeiro), para você migrar sem perder entregas. Após 24h, só o secret novo assina.

curl -X POST https://api.userepass.com/webhook-endpoints/whep_01HZX9QK7M3R8V4N2P6T0YBC5D/rotate-secret \
  -H "Authorization: Bearer rstr_..." \
  -H "Idempotency-Key: c0ffee00-0000-4000-8000-000000000002"

A resposta é o endpoint completo (igual ao detalhe) acrescido do campo secret em claro. O secret atual fica mascarado em maskedSecret, e o fim da graça vem em previousSecretExpiresAt.

{
  "id": "whep_01HZX9QK7M3R8V4N2P6T0YBC5D",
  "url": "https://app.exemplo.com.br/hooks/repass",
  "status": "active",
  "disabledReason": null,
  "maskedSecret": "rwhs_***lcmU",
  "secret": "rwhs_bmV3X3JvdGF0ZWRfc2VjcmV0X2hlcmU",
  "previousSecretExpiresAt": "2026-06-14T12:00:00.000Z",
  "createdAt": "2026-06-13T12:00:00.000Z",
  "updatedAt": "2026-06-13T12:00:00.000Z"
}

A resposta também devolve o secret novo em claro (única vez). Como validar os dois v1= no receptor: Assinatura.

Testar um endpoint

POST /webhook-endpoints/{endpointId}/test entrega uma mensagem sintética webhook.test, assinada como uma entrega normal, na hora (one-shot síncrono). Esse evento não é gravado no event store e a entrega tem eventId: null: sucesso vira succeeded, falha vai direto para dead_letter (sem entrar na fila de retry).

curl -X POST https://api.userepass.com/webhook-endpoints/whep_01HZX9QK7M3R8V4N2P6T0YBC5D/test \
  -H "Authorization: Bearer rstr_..." \
  -H "Idempotency-Key: c0ffee00-0000-4000-8000-000000000003"

O corpo entregue tem o mesmo envelope dos eventos reais, com type: "webhook.test" e payload { "message": "Repass webhook test delivery" }. Use-o para validar conectividade e a verificação de assinatura antes de assinar eventos de produção.

Inspecionar e reenviar entregas

Cada tentativa de entrega fica registrada com request, response, status e latência por 30 dias. Dead letters ficam sem prazo, prontos para replay manual.

GET /webhook-endpoints/{endpointId}/deliveries: log de entregas dos últimos 30 dias (cursor DESC). Filtro opcional status (pending, attempting, succeeded, failed, dead_letter).
GET /webhook-endpoints/{endpointId}/dead-letter: entregas exauridas aguardando replay manual (sem janela de 30 dias).
POST /deliveries/{deliveryId}/replay: reenfileira uma entrega referenciando a original (202); exige o endpoint ativo (senão 409 conflict).

curl -X POST https://api.userepass.com/deliveries/whdl_01HZXC4P8N2R6S0T3V5WCD7E9F/replay \
  -H "Authorization: Bearer rstr_..." \
  -H "Idempotency-Key: c0ffee00-0000-4000-8000-000000000004"

O replay não altera a entrega original: cria uma nova entrega pending que aponta para a original via replayOfId, processada com o cronograma de retry completo. Detalhes do cronograma, dead letter e auto-disable: Retries e dead letter.

Regras de negócio

Assinatura por endpoint e HMAC

Cada endpoint assina um subconjunto da taxonomia (validado contra o catálogo). A entrega leva o header Repass-Signature: t=<unix>,v1=<hmac>, com HMAC-SHA256 sobre "{t}.{body}". O secret sai em claro apenas no create e no rotate-secret; em qualquer outro lugar vem mascarado. A rotação tem graça de 24h com assinatura dupla. Tolerância de replay sugerida: 5 minutos (validada pelo receptor). Veja Assinatura.

Retry exponencial, dead letter e auto-disable

Cronograma de 7 tentativas: 0s, 30s, 5m, 30m, 2h, 12h, 24h. Após a exaustão, a entrega vai para dead letter (consultável e replayável sem prazo). Um endpoint com taxa de falha ≥ 95% em uma janela de 72h (amostra mínima de 20 tentativas) é desativado automaticamente com disabledReason: failure_rate. Veja Retries e dead letter.

Log de entregas de 30 dias

O log de entregas (request, response, status, latência) fica disponível por 30 dias. Dead letters não expiram, para permitir replay manual a qualquer momento.

Próximos passos

Assinatura

Como validar o header Repass-Signature e deduplicar entregas.

Retries e dead letter

Cronograma de retry, dead letter, replay e auto-disable.

Catálogo de eventos

Todos os tipos de evento que você pode assinar.

Eventos

O histórico de eventos da sua organização, consultável via API.

Introdução

Convenções da API

Conceitos

Webhooks & Eventos

Guias

Criar um endpoint

Payload entregue

Gerenciar endpoints

Ciclo de vida do endpoint

Rotacionar o secret

Testar um endpoint

Inspecionar e reenviar entregas

Regras de negócio

Próximos passos

Assinatura

Retries e dead letter

Catálogo de eventos

Eventos

​Criar um endpoint

​Payload entregue

​Gerenciar endpoints

​Ciclo de vida do endpoint

​Rotacionar o secret

​Testar um endpoint

​Inspecionar e reenviar entregas

​Regras de negócio

​Próximos passos

Assinatura

Retries e dead letter

Catálogo de eventos

Eventos

Criar um endpoint

Payload entregue

Gerenciar endpoints

Ciclo de vida do endpoint

Rotacionar o secret

Testar um endpoint

Inspecionar e reenviar entregas

Regras de negócio

Próximos passos