Webhooks

Receive real-time notifications about email events via HTTP callbacks.

Webhooks allow your application to receive real-time notifications when events occur in your SendMailOS account. When an event is triggered, we send an HTTP POST request to your configured endpoint with event details.

Available Events

Email Events

email.sent

Triggered when an email is successfully sent to the recipient's mail server

email.delivered

Triggered when the email is confirmed delivered to the recipient's inbox

email.opened

Triggered when the recipient opens the email (requires tracking pixel)

email.clicked

Triggered when the recipient clicks a link in the email

email.bounced

Triggered when an email bounces (hard or soft bounce)

email.complained

Triggered when a recipient marks the email as spam

Subscriber Events

subscriber.created

Triggered when a new subscriber is added to your list

subscriber.updated

Triggered when subscriber details are modified

subscriber.unsubscribed

Triggered when a subscriber opts out of your emails

Campaign Events

campaign.sent

Triggered when a campaign finishes sending to all recipients

Workflow Events

workflow.started

Triggered when a workflow execution begins for a subscriber

workflow.completed

Triggered when a workflow execution completes all steps

Payload Format

All webhook payloads follow a consistent JSON structure. Here is an example payload for an email.delivered event:

{
  "id": "evt_1234567890abcdef",
  "type": "email.delivered",
  "created_at": "2024-01-15T10:30:00Z",
  "data": {
    "email_id": "em_abc123",
    "message_id": "<[email protected]>",
    "recipient": "[email protected]",
    "campaign_id": "camp_xyz789",
    "timestamp": "2024-01-15T10:30:00Z",
    "metadata": {
      "subscriber_id": "sub_456",
      "tags": ["newsletter", "weekly"]
    }
  }
}

Integration Examples

# Register a webhook endpoint
curl -X POST https://api.sendmailos.com/api/v1/webhooks \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/sendmail",
    "events": ["email.delivered", "email.bounced", "email.complained"],
    "secret": "whsec_your_signing_secret"
  }'

Signature Verification

All webhook requests include a signature in the X-Sendmail-Signature header. You should verify this signature to ensure the request came from SendMailOS and was not tampered with.

Signature Headers

These headers are included in every webhook request

X-Sendmail-SignatureHMAC-SHA256 signature

X-Sendmail-TimestampUnix timestamp of request

X-Sendmail-EventEvent type (e.g., email.delivered)

# Verify signature using OpenSSL
TIMESTAMP="1705315800"
PAYLOAD='{"id":"evt_123",...}'
SECRET="whsec_your_signing_secret"

SIGNATURE=$(echo -n "${TIMESTAMP}.${PAYLOAD}" | \
openssl dgst -sha256 -hmac "$SECRET" | \
sed 's/^.* //')

echo "Expected signature: $SIGNATURE"

Retry Handling

If your endpoint returns a non-2xx status code or times out (30 seconds), we will retry the webhook delivery using exponential backoff.

Retry Schedule

We attempt delivery up to 3 times with exponential backoff

Attempt 1Immediate

Attempt 2After 1 minute

Attempt 3After 5 minutes

Final attemptAfter 30 minutes

Best Practice: Always return a 200 status code as quickly as possible, even if you need to process the webhook asynchronously. This prevents unnecessary retries and ensures reliable delivery.