Webhooks

A Dyvit recebe notificações em tempo real de três fontes: WhatsApp (mensagens de devedores), Mercado Pago (confirmações de pagamento Pix) e Stripe (eventos de billing). Cada webhook possui verificação de assinatura e trilha de auditoria.

---

Quando um devedor responde via WhatsApp, a Meta envia a mensagem para o endpoint da Dyvit. O agente de IA processa a mensagem e responde automaticamente.

A Meta assina cada payload com HMAC-SHA256 usando o webhook secret configurado. A Dyvit valida o header x-hub-signature-256 antes de processar qualquer mensagem.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "5511999999999",
              "phone_number_id": "PHONE_NUMBER_ID"
            },
            "contacts": [
              {
                "profile": { "name": "Maria Silva" },
                "wa_id": "5511987654321"
              }
            ],
            "messages": [
              {
                "from": "5511987654321",
                "id": "wamid.HBgNNTUxMTk4NzY1NDMyMRUCABIY...",
                "timestamp": "1711036800",
                "type": "text",
                "text": {
                  "body": "Oi, quero negociar minha dívida"
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

A Meta exige um endpoint GET para verificar a propriedade do webhook durante a configuração:

A Meta envia os query params hub.mode, hub.verify_token e hub.challenge. A Dyvit valida o verify_token e retorna o challenge como resposta.

---

Quando um devedor paga via Pix, o Mercado Pago envia uma notificação instantânea (IPN) para a Dyvit. Este é o webhook que dispara todo o fluxo de confirmação de pagamento.

{
  "action": "payment.updated",
  "data": {
    "id": "82347691205"
  }
}

O campo data.id é o ID do pagamento no Mercado Pago. A Dyvit busca os detalhes completos via API do Mercado Pago para confirmar status e valor antes de marcar como pago.

Cada webhook é deduplicado pela combinação (source, externalId, action). Se o Mercado Pago reenviar a mesma notificação, a Dyvit ignora o duplicado e retorna 200.

---

Quando o webhook do Mercado Pago confirma um pagamento aprovado, a Dyvit executa automaticamente seis etapas:

---

Eventos de billing (assinatura criada, pagamento de plano, cancelamento) são recebidos via webhook do Stripe.

O Stripe envia o payload completo do evento. A Dyvit verifica a assinatura via stripe-signature header usando constructEvent do SDK do Stripe.

Assim como o Mercado Pago, cada evento do Stripe é deduplicado por (source, externalId, action) na tabela WebhookEvent.

---

Cada provedor usa um mecanismo diferente de verificação. A tabela abaixo resume como a Dyvit valida cada um:

WhatsApp: a Dyvit calcula sha256=HMAC(secret, rawBody) e compara com o header x-hub-signature-256 usando timingSafeEqual para prevenir timing attacks.

Mercado Pago: o Mercado Pago envia o header x-signature no formato ts=...,v1=.... A Dyvit reconstrói o manifest id:{dataId};request-id:{xRequestId};ts:{ts}; e compara o HMAC com v1 usando timingSafeEqual.

Stripe: a Dyvit usa stripe.webhooks.constructEvent(rawBody, signature, webhookSecret) do SDK oficial, que lida com verificação e parsing internamente.

---

Todos os webhooks (WhatsApp, Mercado Pago e Stripe) são registrados na tabela WebhookEvent com os seguintes campos:

Essa tabela permite rastrear cada webhook recebido, identificar falhas e reprocessar eventos quando necessário.

---