Webhooks

Explore 4 endpoints de Webhooks, com finalidade, método e rota derivados do contrato publicado.

Endpoints relacionados

Abra um endpoint para consultar parâmetros, exemplos e respostas.

GETListar eventos configurados/webhook/resource/organization-eventsPUTConfigurar eventos/webhook/resource/eventsPOSTEnviar evento de teste/webhook/resource/test-sendGETHistórico de entregas/webhook/resource/send-events

Quando usar cada endpoint

Compare a finalidade de cada operação antes de iniciar a integração.

EndpointFinalidade
GET/webhook/resource/organization-eventswebhook.events.organization_id é único, então existe no máximo uma configuração por organização. O secret não é retornado; apenas o indicador hasSecret.
PUT/webhook/resource/eventsUpsert por organizationId. Campos ausentes são preservados; enviar null em uma URL desliga a notificação daquele status. O secret é sempre gerado pelo serviço — nunca aceito no corpo — e só é rotacionado com regenerateSecret: true. O secret é devolvido uma única vez, em data.secret, apenas na resposta que o gerou (primeira configuração ou regenerateSecret: true); nas demais respostas data é null. Ele não pode ser recuperado depois — quem perdeu o valor rotaciona. organizationId é o da sua organização (o mesmo que aparece em organizationId nas carteiras).
POST/webhook/resource/test-sendEnvia para a URL configurada do status informado em data.status um POST igual ao de um evento real, assinado quando há secret. Use-o para validar seu endpoint antes de operar. Nenhuma transação é criada. Se não houver URL configurada para o status, nada é enviado.
GET/webhook/resource/send-eventsHistórico de entregas dos webhooks da organização: cada linha é um envio para a sua URL, com o status HTTP que ela respondeu e o total de tentativas. Use para investigar um evento que não chegou. organizationId é obrigatório; refine por carteira, transação, externalId e intervalo de datas.

Finalidades, métodos e rotas vêm do contrato OpenAPI publicado.

Fluxo da categoria

A ordem das chamadas, quem executa cada passo e o que vem depois. Clique numa chamada para ver o fluxo dela.

Configurar e operar

  1. Chamada

    PUTConfigurar eventos

    /webhook/resource/events

    Uma URL por estado da transação

  2. Chamada

    GETListar eventos configurados

    /webhook/resource/organization-events

    Confira as URLs e se há secret

  3. Chamada

    POSTEnviar evento de teste

    /webhook/resource/test-send

    Evento igual ao real, sem criar transação

  4. Você

    Seu endpoint recebe

    Valida a assinatura e responde 2xx rápido

  5. Chamada

    GETHistórico de entregas

    /webhook/resource/send-events

    Confira status HTTP e tentativas de cada envio