Webhooks

Receive real-time notifications when message events occur.

Overview

Webhooks let you subscribe to events like message delivery, opens, clicks, and bounces. When an event occurs, YourSend sends an HTTP POST request to your configured endpoint.

Setup

1. Go to Dashboard → Settings → Webhooks
2. Click Add Endpoint
3. Enter your HTTPS URL (e.g., https://yourapp.com/api/webhooks/yoursend)
4. Select the events you want to subscribe to
5. Copy the signing secret for verification

Event Types

Payload Format

{
  "event": "message.delivered",
  "timestamp": "2026-03-18T12:00:02Z",
  "data": {
    "message_id": "msg_abc123def456",
    "to": "user@example.com",
    "channel": "email",
    "status": "delivered",
    "metadata": {}
  }
}

Signature Verification

Each webhook request includes a X-YourSend-Signature header. Verify it using HMAC-SHA256 with your signing secret:

import crypto from 'crypto';

function verifyWebhook(
  body: string,
  signature: string,
  secret: string,
): boolean {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected),
  );
}