Guides

Webhooks

Suggest Edits

O que é webhook?

Webhook (ou retorno de chamada HTTP) é uma forma de receber informações em tempo real. Quando uma API tem a possibilidade de enviar uma notificação ela fornecerá um conjunto de informações reportando ao usuário que tal evento ocorreu.

Como nossos webhooks funcionam?

Nossa API's adotam uma arquitetura orientada a eventos, operando de maneira assíncrona para otimizar suas operações. Ao realizar a pesquisa de débitos ou pagamentos, todas as atualizações serão enviadas diretamente para o seu sistema via webhooks através de chamadas HTTP POST contendo dados em JSON diretamente para a sua URL configurada. Isso assegura que você receba informações em tempo real, permitindo que seu sistema responda imediatamente e prossiga com as ações necessárias.

📘

Reenvio de webhook

Ao cadastrar uma URL para receber nossas notificações, você poderá especificar quantas vezes podemos reenviar enviar aquele webhook em caso de falha em seu endpoint.

Você também poderá consultar os webhooks que falharam e forçar o seu reenvio manualmente.

🚧

Informações de segurança

Por medidas de segurança, todas as nossas requisições possuem um código de autenticação de mensagem baseado em hash contido no header x-hmac-signature. Para garantir a autenticidade da mensagem, você poderá realizar um hash sha256 do corpo da requisição recebida em seu endpoint webhook utilizando sua secret_key e comparar com o valor contido no x-hmac-signature.

Como camada de segurança adicional, você poderá informar um token de autenticação complementar (JWT ou APIKey) no momento de cadastro do seu endpoint, feito isso adicionaremos um header (authorization ou x-api-key) em todas as chamadas ao endpoint cadastrado.

Para assegurar uma comunicação eficaz, realizamos uma verificação inicial quando você registra seu endpoint de webhook. Este processo começa com uma chamada de validação assim que você nos fornece seus detalhes.

Cadastro de um novo webhook

Para cadastrar um novo webhook, você deverá seguir o modelo de requisição abaixo:

Request para cadastrar um novo webhook:

curl --location 'https://api.b2b.usezapay.com.br/v2/webhook/' \
--header 'Authorization: JWT TOKEN_JWT_VALIDO' \
--header 'Content-Type: application/json' \
--data '{
  "auth": {
    "prefix": "Bearer",
    "type": "JWT",
    "value": "TOKEN_DE_AUTENTICAÇÃO_DA_SUA_URL"
  },
  "resource": "vehicle_debt",
  "url": "https://url-mockada.com.br"
}'

Após enviar a requisição, você receberá uma chamada HTTP POST para confirmar a validação na URL especificada, no seguinte formato:

Webhook de validação que será entregue na URL cadastrada:

{
  "id": "B1234",
  "event": "webhook_validation",
  "webhook": {
    "id": null,
    "resource": "vehicle_debt",
    "version": "v2"
  },
  "data": {}
}

Se a validação for bem-sucedida, ou seja, a URL cadastrada responder com um HTTP status code 2XX, seu webhook será cadastrado com sucesso e você receberá uma resposta HTTP 200 OK, acompanhado por um payload confirmando o registro:

Resultado do cadastro de um webhook

{
  "id": "hook_123456",
  "created_at": "2023-10-24T15:41:54.506308",
  "resource": "vehicle_debts",
  "updated_at": "2023-10-24T16:42:54.506308",
  "url": "https://url-mockada.com.br",
  "version": "v2"
}

Agora que seu endpoint webhook foi configurado corretamente, você está apto a prosseguir com nossas integrações.

Política de retentativas

Uma falha é caracterizada por qualquer resposta do endpoint que não esteja na faixa de status HTTP 2XX ou que exceda o tempo de resposta de 30 segundos. A menos que o erro retornado pelo endpoint faça parte de nossa lista de erros irrecuperáveis, procederemos com uma nova tentativa 10 segundos após o último erro, limitando-se a um total de 3 tentativas de reenvio.

Erros não recuperáveis

Alguns erros retornados pelo seu endpoint serão considerados como não recuperáveis pela Zapay e a chamada não será retentada se receber os seguintes HTTP status code:

  • 400: O endpoint existe, mas não pode processar o payload.
  • 401: O endpoint está protegido por autenticação ou não reconhece o token/key do webhook.
  • 403: O endpoint não permite que a Zapay realize a chamada.
  • 404: Endpoint não encontrado.
  • 406: O endpoint existe, mas rejeitou a chamada webhook intencionalmente.

🚧

Ordem dos eventos

Nosso objetivo é sempre enviar os webhooks na mesma sequência em que os eventos ocorrem. No entanto, devido a característica assíncrona do nosso sistema, não podemos assegurar que os eventos sejam entregues exatamente na ordem em que são gerados em 100% dos casos.

🚧

Duplicidades

Em situações excepcionais, especialmente quando um usuário executa várias ações em um intervalo de tempo muito curto, pode acontecer de sua aplicação receber o mesmo evento mais de uma vez no mesmo período. Embora isso geralmente não represente um problema para a maioria das aplicações, é crucial que seu sistema esteja preparada para lidar com essas ocorrências.

Para assegurar a consistência e a confiabilidade dos processos, sua aplicação deve ser projetada para ser idempotente. Isso significa que, mesmo diante de eventos duplicados, o resultado final não deve ser afetado.

Webhooks disponíveis

Abaixo segue uma lista de produtos Zapay onde é possível receber webhooks:

📘

Informações dos webhooks

Os campos em cada webhook são baseados em seus respectivos produtos, portanto, suas propriedades, formatos e informações seguem os mesmos dos campos nos endpoints de cada um.

Updated 6 months ago