Webhooks

Subscribe to real-time event notifications. TopMail sends HTTP POST requests to your endpoint whenever subscribed events occur, with HMAC signature verification for security.

Event Types

Event	Description
contact.created	A new contact was created
contact.updated	A contact was updated
contact.subscribed	A contact subscribed to a list
contact.unsubscribed	A contact unsubscribed from a list
campaign.sent	A campaign started sending
campaign.completed	A campaign finished sending
email.sent	An individual email was sent
email.delivered	An email was delivered
email.opened	An email was opened
email.clicked	A link in an email was clicked
email.bounced	An email bounced
email.complained	A recipient marked an email as spam
flow.triggered	A flow automation was triggered
flow.completed	A flow automation completed
form.submitted	A form was submitted
conversion.created	A conversion was tracked
list.member_added	A contact was added to a list
list.member_removed	A contact was removed from a list

Subscribe to Events

POST

/webhooks/triggers

Create a webhook subscription for a specific event type

Name	Type	Required	Description
targetUrl	string	Required	The URL that will receive webhook POST requests
event	string	Required	The event type to subscribe to (see event types above)

curl -X POST https://api.topmail.so/api/v1/webhooks/triggers \
  -H "Authorization: Bearer tm_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "targetUrl": "https://yourapp.com/webhooks/topmail",
    "event": "email.delivered"
  }'

{
  "data": {
    "id": "webhook-uuid-12345",
    "event": "email.delivered",
    "targetUrl": "https://yourapp.com/webhooks/topmail",
    "createdAt": "2025-01-15T08:30:00.000Z"
  }
}

Unsubscribe

DELETE

/webhooks/triggers?id=:webhookId

Remove a webhook subscription

Name	Type	Required	Description
id	string	Required	The webhook subscription ID (query parameter)

curl -X DELETE "https://api.topmail.so/api/v1/webhooks/triggers?id=webhook-uuid-12345" \
  -H "Authorization: Bearer tm_live_abc123"

{
  "data": {
    "success": true
  }
}

Test Webhook

POST

/webhooks/:id/test

Send a test event to verify your webhook endpoint is working

Name	Type	Required	Description
id	string	Required	The webhook subscription ID (URL parameter)

curl -X POST https://api.topmail.so/api/v1/webhooks/webhook-uuid-12345/test \
  -H "Authorization: Bearer tm_live_abc123"

{
  "data": {
    "success": true,
    "status_code": 200,
    "response_time_ms": 145
  }
}

Signature Verification

Every webhook request includes a signature in the X-TopMail-Signature header. You should verify this signature to ensure the request is authentic and has not been tampered with.

Headers

Header	Description
X-TopMail-Signature	HMAC-SHA256 signature: t=<timestamp>,v1=<hash>
X-TopMail-Event	The event type (e.g., email.delivered)
X-TopMail-Delivery-Id	Unique delivery ID for deduplication
X-TopMail-Webhook-Id	Your webhook subscription ID

Verification Example

# The signature is computed as:
# HMAC-SHA256(secret, "<timestamp>.<json_body>")
#
# Parse the X-TopMail-Signature header:
# t=1705312200,v1=a1b2c3d4e5f6...
#
# Verify: recompute the HMAC and compare with v1 value

Webhook Payload Format

Webhook payloads are JSON objects with three fields:event (the event type),timestamp (ISO 8601), and data (event-specific payload).