Webhooks

Os webhooks da DEUNA abrangem dois fluxos diferentes de servidor para servidor: notificações que publicam alterações de estado de pagamento para seu backend e callbacks síncronos que permitem que a DEUNA solicite dados ou lógica específicos do comerciante durante o checkout. Escolha o fluxo de acordo com o que sua integração precisa realizar.

Redirecionamentos de navegador, callbacks do SDK e callbacks de provedor para DEUNA são superfícies de integração separadas. Não os use como prova de pagamento ou como substitutos para esses fluxos de backend.

Notificações de status de pedido e pagamentoPerguntar à Athia sobre isto#

As notificações de status entregam o snapshot mais recente do pedido ao seu backend quando o status de pagamento normalizado corresponde a um evento inscrito para o merchant. Essas notificações são assíncronas: o ciclo de vida do pagamento não aguarda a conclusão da sua lógica de negócio.

Configurar entrega de status

Defina o contrato de entrega para cada ambiente:

Os eventos disponíveis seguem o ciclo de vida de pagamento documentado em Fluxo e status de pagamento. A cobertura de eventos pode variar por método de pagamento porque nem todo método suporta cada operação ou status de pagamento.

Carga útil padrão

Sem uma transformação personalizada do payload, a DEUNA envia um HTTP POST com Content-Type: application/json e o pedido atual sob a propriedade order :

{
  "order": {
    "token": "21ac49c0-d587-4f25-ae1c-0d60e540c1e8",
    "order_id": "merchant-order-123",
    "transaction_id": "transaction-456",
    "status": "succeeded",
    "payment_status": "processed",
    "currency": "USD",
    "total_amount": 5000,
    "payment": {
      "data": {
        "status": "processed",
        "processor": "example_processor",
        "external_transaction_id": "processor-789"
      }
    }
  }
}

O pedido pode conter os dados de cliente, item, valor, pagamento, processador, fraude, metadados e campo personalizado associados a essa transação. Trate order.payment.data.status como o estado de pagamento autoritativo, e use order.token, order.order_ide os identificadores de transação aplicáveis para reconciliação.

Uma configuração específica do lojista pode alterar o método HTTP, headers, parâmetros de URL, status assinados e formato do payload. Se uma configuração personalizada estiver habilitada, implemente o contrato exato certificado para esse lojista em vez de assumir o corpo padrão.

Verifique a assinatura

A entrega atual adiciona um X-Signature cabeçalho. Isso substitui exemplos mais antigos que se referem a X-Deuna-Signature.

1. Leia o corpo da requisição não modificado antes que um framework o analise ou resserialize.
2. Aplique o procedimento de verificação HMAC-SHA256 e Base64 certificado para o fluxo e ambiente de entrega.
3. Compare o valor calculado com X-Signature usando uma comparação de tempo constante.
4. Rejeite a requisição antes do processamento se os valores não corresponderem.

Notificações de status e webhooks dinâmicos nem sempre assinam a mesma entrada quando a transformação de payload está ativada. Não reutilize um verificador entre esses fluxos até que a entrada assinada e a derivação da chave tenham sido confirmadas durante a certificação.

Mantenha as chaves de API privadas no servidor. Nunca as coloque em código de navegador, aplicativos móveis, logs ou respostas de webhook.

Reconheça e reconcilie

1. Verifique a assinatura antes de confiar no payload.
2. Registre uma chave de deduplicação que inclua o token do pedido e o evento ou status de pagamento resultante.
3. Retorne uma resposta 2xx bem-sucedida assim que a requisição for aceita de forma durável.
4. Releia ou reconcilie o estado autoritativo do pedido antes de cumprimento, cancelamento, captura, reembolso ou outra ação irreversível.
5. Ignore uma notificação que moveria seu registro local para trás a partir de um estado mais recente.

Falhas de entrega podem ser repetidas. Não assuma entrega exatamente uma vez, um intervalo de repetição fixo ou chegada na ordem do ciclo de vida.

Webhooks de checkout dinâmicoPerguntar à Athia sobre isto#

Webhooks dinâmicos são callbacks síncronos e específicos do lojista. Quando o checkout dispara um evento configurado, a DEUNA envia uma requisição assinada para seu endpoint, valida a resposta, aplica apenas as atualizações permitidas e retorna o resultado configurado para o checkout.

Webhooks dinâmicos são ativados e configurados como parte da implementação do lojista. Eles não são registrados a partir de código de navegador ou móvel.

Fluxo de configuração e execução

Configure o webhook com a DEUNA como parte da configuração do seu lojista. Combine o nome do evento, destino, formatos de requisição e resposta, regras de validação e campos que o callback pode atualizar. Após a configuração, o checkout pode executar o evento através do mesmo contrato acordado.

Se o evento não estiver configurado para o lojista e ambiente, a DEUNA não chama seu endpoint. Trate um callback obrigatório que não foi executado como um problema de configuração durante a certificação.

Capacidades de configuração

O trecho a seguir mostra o núcleo de uma definição de cálculo de gorjeta. São dados de configuração, não uma solicitação que deve ser enviada do navegador:

{
  "event_name": "tip_amount_updated",
  "url": "https://merchant.example.com/checkout/tips",
  "http_method": "POST",
  "fields_update": {
    "fields": ["TotalAmount"],
    "custom_fields": ["tipAmount"]
  },
  "response_body": {
    "fields": ["Order"],
    "custom_fields": ["tipAmount"]
  },
  "response_template": "{\"order\":{\"total_amount\":{{ .result.total_amount }},\"custom_fields\":{\"tipAmount\":{{ .result.tip_amount }}}}}",
  "response_data": "{\"result\":{\"total_amount\":5500,\"tip_amount\":500}}"
}

Durante a execução, o checkout pode fornecer entrada específica do evento:

{
  "data": {
    "tip_amount": 500
  }
}

Sem um modelo de payload, o endpoint do lojista recebe esses dados do evento. Com um modelo de payload, o modelo pode usar tanto o pedido atual quanto a entrada do evento para construir o JSON de saída.

Implemente o endpoint do lojista

Chamadas dinâmicas incluem X-Signature e X-Deuna-Operation. Quando um modelo de payload altera o corpo de saída, use a entrada de verificação de assinatura acordada durante a certificação; não assuma que é idêntica ao contrato de notificação de status acima.

Se a propagação da resposta estiver desativada, a resposta padrão do lojista pode conter order, shipping_ratee shipping_methods; a DEUNA retorna apenas os campos de resposta selecionados pela configuração. Se a propagação da resposta estiver ativada, a resposta do lojista deve ser JSON válido e é retornada diretamente como o resultado dinâmico.

Padrões práticos

Exemplo de cálculo de gorjeta

Este exemplo mostra o caminho completo do checkout para o lojista para um evento de gorjeta configurado.

Para uma definição de gorjeta, permita apenas o valor e os campos personalizados que se espera que a resposta do lojista altere. O endpoint do lojista permanece responsável por calcular um total de pedido consistente.

Teste no ambiente de sandboxPerguntar à Athia sobre isto#

Testar notificações de status

Testar um webhook dinâmico

Documentação relacionadaPerguntar à Athia sobre isto#