Webhooks (Callback)

A API da Meta integrada ao Ótima Provider envia callbacks (webhooks) em tempo real para a URL configurada em cada número.

Esses callbacks representam eventos que acontecem dentro do WhatsApp e permitem que sua aplicação reaja automaticamente.

Os Webhooks seguem o padrão oficial da Meta (WhatsApp Business Platform) e permitem monitorar:

• Mensagens recebidas

• Status de mensagens enviadas

• Eventos de cobrança (pricing/conversation)

• Interações com mensagens interativas

• Atualizações de templates (HSM)

• Recebimento de arquivos/mídia (áudio, imagem, vídeo, documento, etc.)

---

Estrutura Padrão do Webhook

Todos os webhooks seguem o padrão oficial da Meta:

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WABA_ID",
      "changes": [
        {
          "field": "messages",
          "value": {}
        }
      ]
    }
  ]
}

O conteúdo relevante do evento estará sempre em:

entry[].changes[].value

---

Mensagem Recebida (Inbound)

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WABA_ID",
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "5511999999999",
              "phone_number_id": "PHONE_NUMBER_ID"
            },
            "contacts": [
              {
                "profile": {
                  "name": "João Silva"
                },
                "wa_id": "5511988887777"
              }
            ],
            "messages": [
              {
                "from": "5511999999999",
                "id": "wamid.ID_DA_MENSAGEM",
                "timestamp": "1700000000",
                "type": "text",
                "text": {
                  "body": "Olá!"
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

---

Recebimento de Arquivos (Mídia)

Quando o usuário envia um arquivo, o webhook incluirá um objeto específico conforme o tipo da mídia.

Importante sobre URLs de mídia

A Meta fornece uma URL temporária protegida:

"url": "https://lookaside.fbsbx.com/..."

Essa URL:

• Expira após um período

• Requer autenticação

Ex:

curl --location 'https://lookaside.fbsbx.com/whatsapp_business/attachments/?mid=19879042342750386&source=webhook&ext=1143812251&hash=ARlrSsMJHJKO4YYRDRyrwexwgRHHl5cJTqfmPZY8WR8WQFMg' \
--header 'Authorization: Bearer {SEU TOKEN}’

Diferencial do Meta - Ótima Provider

Além da URL original da Meta, fornecemos:

"s3_url": "https://s3.otima.io/..."

Essa URL:

• É pública

• Não expira

• Pode ser usada diretamente para download

• Ideal para armazenamento e processamento

---

Tipos de Arquivos Suportados

Áudio

{
  "type": "audio",
  "audio": {
    "id": "MEDIA_ID",
    "mime_type": "audio/ogg; codecs=opus",
    "sha256": "HASH",
    "url": "URL_META",
    "s3_url": "URL_PUBLICA"
  }
}

---

Imagem

{
  "type": "image",
  "image": {
    "id": "MEDIA_ID",
    "mime_type": "image/jpeg",
    "sha256": "HASH",
    "caption": "Legenda opcional",
    "url": "URL_META",
    "s3_url": "URL_PUBLICA"
  }
}

---

Vídeo

{
  "type": "video",
  "video": {
    "id": "MEDIA_ID",
    "mime_type": "video/mp4",
    "sha256": "HASH",
    "caption": "Legenda opcional",
    "url": "URL_META",
    "s3_url": "URL_PUBLICA"
  }
}

---

Documento

{
  "type": "document",
  "document": {
    "id": "MEDIA_ID",
    "mime_type": "application/pdf",
    "filename": "arquivo.pdf",
    "sha256": "HASH",
    "url": "URL_META",
    "s3_url": "URL_PUBLICA"
  }
}

---

Sticker

{
  "type": "sticker",
  "sticker": {
    "id": "MEDIA_ID",
    "mime_type": "image/webp",
    "sha256": "HASH",
    "url": "URL_META",
    "s3_url": "URL_PUBLICA"
  }
}

---

Exemplo Completo (Mensagem com Áudio)

O exemplo abaixo representa o formato completo de um webhook oficial da Meta (WhatsApp Business Platform) para o recebimento de mensagens.

Embora o exemplo utilize um áudio, essa mesma estrutura se aplica a todos os tipos de mídia suportados, como:

• audio

• image

• video

• document

• sticker

A única variação será o campo type e o objeto correspondente dentro de messages[].

Além disso, o Meta - Ótima Provider adiciona o campo s3_url, que fornece uma URL pública já para download da mesma mídia.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WABA_ID",
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "contacts": [
              {
                "wa_id": "551199991111",
                "profile": {
                  "name": "Marcos"
                }
              }
            ],
            "messages": [
              {
                "id": "wamid.ID",
                "from": "556182897860",
                "timestamp": "1700000000",
                "type": "audio",
                "audio": {
                  "id": "MEDIA_ID",
                  "mime_type": "audio/ogg; codecs=opus",
                  "sha256": "HASH",
                  "url": "URL_META",
                  "s3_url": "URL_PUBLICA"
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

---

Status de Mensagem

Status possíveis:

• sent

• delivered

• read

• failed

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WABA_ID",
      "changes": [
        {
          "field": "messages",
          "value": {
            "statuses": [
              {
                "id": "wamid.ID_DA_MENSAGEM",
                "status": "delivered",
                "timestamp": "1700000000",
                "recipient_id": "5511988887777",
                "conversation": {
                  "id": "CONVERSATION_ID",
                  "origin": {
                    "type": "marketing"
                  }
                },
                "pricing": {
                  "billable": true,
                  "pricing_model": "CBP",
                  "category": "marketing"
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

---

Mensagem Interativa

{
  "messages": [
    {
      "from": "5511988887777",
      "id": "wamid.ID",
      "timestamp": "1700000000",
      "type": "interactive",
      "interactive": {
        "type": "button_reply",
        "button_reply": {
          "id": "btn_1",
          "title": "Confirmar"
        }
      }
    }
  ]
}

---

Atualização de Status de Template

Eventos possíveis:

• APPROVED

• REJECTED

• PENDING

• DISABLED

{
  "field": "message_template_status_update",
  "value": {
    "message_template_id": "123456789",
    "message_template_name": "boas_vindas",
    "message_template_language": "pt_BR",
    "event": "APPROVED"
  }
}

---

Boas práticas

• Responder com HTTP 200 OK

• Validar assinatura X-Hub-Signature-256

• Processar eventos de forma assíncrona