Webhooks

Webhooks allow your application to receive real-time HTTP push notifications when specific events occur within your Senda tenant.

Instead of polling the API for updates, Senda will send an HTTP POST request to a URL you configure whenever a subscribed event takes place.

Configuring Webhooks

Currently, Webhook subscriptions must be managed via the Senda Admin UI or the Admin API (/api/webhook-subs). When creating a subscription, you must provide:

1. Name: A descriptive name for the webhook.
2. URL: The endpoint on your server that will receive the POST requests.
3. Event Filter: A pattern (e.g., agent.*, chat.message_sent, or *) to determine which events trigger the webhook.
4. Signing Secret: (Optional but highly recommended) A secret key used to cryptographically sign the webhook payloads.

Webhook Payload

When an event occurs, Senda sends an HTTP POST to your configured URL. The payload is a JSON object containing the event details.

Example Payload:

{
  "event_id": "evt_abc123",
  "event_type": "chat.message_sent",
  "created_at": "2026-05-10T15:30:00Z",
  "tenant_id": "tnt_prod",
  "data": {
    "chat_id": "chat_xyz789",
    "message": "Hello, how can I help you?",
    "role": "agent",
    "agent_id": "agent_soporte"
  }
}

Verifying Signatures

If you configured a Signing Secret, Senda includes an X-Senda-Signature header in every webhook request. You should verify this signature to ensure the request genuinely came from Senda and was not tampered with.

The signature is an HMAC-SHA256 hash generated using your signing_secret and the raw request body.

Node.js Example:

const crypto = require('crypto');

function verifyWebhookSignature(req, signingSecret) {
  const signature = req.headers['x-senda-signature'];
  const rawBody = req.body; // Ensure this is the raw string body, not parsed JSON
  
  const expectedSignature = crypto
    .createHmac('sha256', signingSecret)
    .update(rawBody)
    .digest('hex');
    
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Retries and Dead Letters

Senda expects your webhook endpoint to respond with a 2xx HTTP status code within a reasonable timeout.

• If your endpoint returns a 4xx or 5xx error, or times out, Senda will retry the delivery with exponential backoff.
• After exhausting all retry attempts, the webhook delivery will be marked as dead_letter.
• Administrators can view the delivery history and manually re-enqueue dead_letter events via the Admin Dashboard or Admin API.