Webhook de status

​

Cadastrar

• A URL precisa usar HTTPS, sem usuário ou senha.
• Endereços internos são recusados: localhost, IPs de rede privada ou reservada e nomes sem domínio público. A checagem acontece ao salvar e de novo a cada envio.
• Na primeira vez que você salva, a tela mostra o segredo (whsec_...) uma única vez. Guarde-o: depois de fechar o aviso, ele não aparece de novo. Ao regenerar o segredo, o antigo deixa de valer na hora e o novo também aparece uma única vez.
• O botão Enviar teste envia um evento webhook.test à URL já salva (sem repetir em caso de falha) e mostra o status HTTP e o tempo de resposta. Com uma edição de URL ainda não salva, o botão fica desabilitado: salve primeiro.

​

Ligar o callback à sua mensagem

​

O callback

{
  "event_id": "3f6c1b0e-5d2a-4a8e-9c1f-0b7d2e4a6c11",
  "type": "message.status",
  "created_at": "2026-10-29T14:03:22.418Z",
  "data": {
    "message_id": "7b0c2f4e-1d3a-4c55-9a52-5f1d7e8a9b10",
    "external_id": "pedido-12345",
    "provider_message_id": "wamid.xxx...",
    "channel": "whatsapp",
    "status": "delivered",
    "occurred_at": "2026-10-29T14:03:22.418Z",
    "error_message": null,
    "failure_code": null
  }
}

{
  "event_id": "9a1d4c2e-7b3f-4e60-8d15-2c6e0f9b3a47",
  "type": "message.status",
  "created_at": "2026-10-29T14:05:10.102Z",
  "data": {
    "message_id": "7b0c2f4e-1d3a-4c55-9a52-5f1d7e8a9b10",
    "external_id": "pedido-12345",
    "provider_message_id": null,
    "channel": "whatsapp",
    "status": "failed",
    "occurred_at": "2026-10-29T14:05:10.102Z",
    "error_message": "Número não está registrado no WhatsApp",
    "failure_code": "recipient_not_on_channel"
  }
}

​

Códigos de falha (failure_code)

​

Verificar a assinatura

X-OctaSend-Signature: t=1761746602,v1=5b1f...e9

const crypto = require('crypto');
const express = require('express');

const SEGREDO = process.env.OCTASEND_WEBHOOK_SECRET; // whsec_...
const TOLERANCIA_S = 300;

function assinaturaValida(rawBody, header) {
  const partes = Object.fromEntries(
    (header || '').split(',').map((p) => p.split(/=(.*)/s).slice(0, 2))
  );
  const t = Number(partes.t);
  if (!t || !partes.v1) return false;
  if (Math.abs(Date.now() / 1000 - t) > TOLERANCIA_S) return false;
  const esperado = crypto
    .createHmac('sha256', SEGREDO)
    .update(`${t}.${rawBody}`)
    .digest('hex');
  const a = Buffer.from(esperado);
  const b = Buffer.from(partes.v1);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

const app = express();
app.post('/webhooks/octasend', express.raw({ type: 'application/json' }), (req, res) => {
  const rawBody = req.body.toString('utf8');
  if (!assinaturaValida(rawBody, req.get('X-OctaSend-Signature'))) {
    return res.sendStatus(401);
  }
  const evento = JSON.parse(rawBody);
  // deduplique por evento.event_id e processe evento.data
  res.sendStatus(200);
});

import hashlib
import hmac
import os
import time

from flask import Flask, request

SEGREDO = os.environ["OCTASEND_WEBHOOK_SECRET"]  # whsec_...
TOLERANCIA_S = 300

app = Flask(__name__)


def assinatura_valida(raw_body: bytes, header: str) -> bool:
    partes = dict(p.split("=", 1) for p in (header or "").split(",") if "=" in p)
    try:
        t = int(partes["t"])
        v1 = partes["v1"]
    except (KeyError, ValueError):
        return False
    if abs(time.time() - t) > TOLERANCIA_S:
        return False
    esperado = hmac.new(
        SEGREDO.encode(), f"{t}.".encode() + raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(esperado, v1)


@app.post("/webhooks/octasend")
def octasend():
    if not assinatura_valida(request.get_data(), request.headers.get("X-OctaSend-Signature")):
        return "", 401
    evento = request.get_json()
    # deduplique por evento["event_id"] e processe evento["data"]
    return "", 200

​

Resposta esperada

​

Tentativas e desativação

• Cada evento tem até 5 tentativas. Depois de uma falha, a próxima vem após 1, 5, 15 e 30 minutos (a verificação roda a cada minuto, então os intervalos podem variar em cerca de 1 minuto).
• Se as 5 tentativas falharem, o evento fica como esgotado. Ele pode ser reenviado manualmente na tela de Configuração geral, com o mesmo event_id.
• Depois de 20 eventos esgotados seguidos (qualquer entrega com sucesso zera a contagem), o webhook é desativado automaticamente e o dono e os administradores ativos da conta (inclusive o perfil Master) recebem um aviso no sino do painel. Depois de corrigir o endpoint, reative-o na tela; a contagem recomeça do zero.
• Enquanto o webhook estiver desativado (por você ou automaticamente), as mudanças de status novas não geram evento. Os eventos que já estavam na fila esperam e são enviados quando você reativar; um evento com mais de 30 dias é encerrado sem envio.
• O histórico de envios e tentativas da tela é guardado por 30 dias.

​

Boas práticas ao receber

• Entrega pelo menos uma vez: o mesmo evento pode chegar mais de uma vez (resposta perdida, reenvio manual). O event_id é o mesmo em todas as tentativas: guarde os já processados e ignore repetidos.
• A ordem não é garantida: um delivered pode chegar antes do sent. Use data.occurred_at para decidir o estado mais recente e não sobrescreva um estado novo por um antigo.
• Responda rápido: devolva 2xx assim que validar e guardar o evento, e processe o resto depois.
• Só mensagens enviadas pela API são notificadas. Envios do painel, campanhas e automações não geram callback.