Cómo configurar y verificar webhooks de la API

Configurar el endpoint

1. Entra como owner a Configuración → API.
2. En Operación y eventos, activa Webhooks firmados.
3. Escribe una URL HTTPS pública en puerto 443 en URL de recepción.
4. Selecciona los eventos que deseas recibir. Hay cinco disponibles.
5. Presiona Generar / rotar secreto, copia el valor completo y guárdalo de forma segura.
6. Presiona Guardar configuración.

Eventos disponibles

• message.received: mensaje entrante persistido en la cuenta.
• message.sent, message.delivered, message.read y message.failed: mensajes originados por la API pública.

Encabezados

Content-Type: application/json
User-Agent: MiSender-Webhooks/1.0
X-MiSender-Event: message.delivered
X-MiSender-Event-Id: evt_...
X-MiSender-Timestamp: 1790964000
X-MiSender-Signature: sha256=...

Payload

{
  "id": "evt_...",
  "type": "message.delivered",
  "created_at": "2026-10-02T18:30:04+00:00",
  "data": {
    "message": {
      "id": "msg_...",
      "status": "delivered",
      "to": "5215555555555",
      "type": "text",
      "external_id": "pedido-84721",
      "metadata": {"pedido_id": 84721}
    }
  }
}

Verificar la firma

Calcula HMAC SHA-256 sobre timestamp + "." + cuerpo JSON exacto. No vuelvas a serializar el JSON antes de verificar.

$rawBody = file_get_contents("php://input");
$timestamp = $_SERVER["HTTP_X_MISENDER_TIMESTAMP"] ?? "";
$received = $_SERVER["HTTP_X_MISENDER_SIGNATURE"] ?? "";
$expected = "sha256=" . hash_hmac("sha256", $timestamp . "." . $rawBody, $webhookSecret);

if (!hash_equals($expected, $received)) {
    http_response_code(401);
    exit;
}

http_response_code(204);

Entrega y duplicados

La semántica es at least once: un evento puede llegar más de una vez. Guarda X-MiSender-Event-Id y procesa cada identificador una sola vez. Responde rápidamente con cualquier código 2xx; mueve el trabajo pesado a tu propia cola.