Webhooks

Webhooks let you receive real-time notifications when email events occur. Instead of polling for status, Artmail sends HTTP POST requests to your endpoint when an email is sent, delivered, opened, clicked, bounced, or complained about.

How Webhooks Work

1. You create a webhook in the dashboard and provide a URL.
2. You subscribe to the event types you care about.
3. When an event occurs, Artmail signs the payload and POSTs it to your URL.
4. Your server verifies the signature, processes the event, and returns 2xx to acknowledge receipt.
5. If your server fails or times out, Artmail retries with exponential backoff (up to 3 retries).

Available Event Types

Event Type	Description
email.sent	Email was queued and accepted for sending
email.delivered	Email was successfully delivered
email.bounced	Email bounced (hard or soft)
email.complained	Recipient marked the email as spam
email.opened	Recipient opened the email (tracking pixel)
email.clicked	Recipient clicked a tracked link
email.unsubscribed	Recipient unsubscribed via link

Select which events to receive when creating or editing a webhook. You can subscribe to any combination of these events.

Webhook Payload Format

All webhook events use this structure:

Field	Type	Description
id	string	Unique event ID (for idempotency).
type	string	Event type (e.g. email.delivered).
timestamp	string	ISO 8601 timestamp.
data	object	Event-specific data.

Event-specific fields in data vary by event type. Common fields: to, from, subject, messageId, emailId. Bounce events may include bounceType, bounceSubType; click events may include linkUrl, etc.

Setting Up Webhooks

Via Dashboard

1. Log in to your Artmail dashboard.
2. Go to Settings → Developer → Webhooks.
3. Click Create Webhook.
4. Enter your Endpoint URL (must be HTTPS and publicly reachable).
5. Select the events you want to receive.
6. Copy the Signing Secret — you need it to verify signatures.

Signature Verification

Artmail signs each webhook payload with HMAC-SHA256. Always verify the signature before processing to ensure the request came from Artmail and wasn't modified.

Signature Algorithm

• Input: {timestamp}.{rawRequestBody}
• Key: Your webhook signing secret
• Output: Hex-encoded HMAC-SHA256 signature

Headers sent with each request:

Header	Description
X-ArtMail-Signature	HMAC-SHA256 hex signature
X-ArtMail-Timestamp	Unix timestamp used in the signed payload
Content-Type	application/json

Node.js Verification Example

Replay Protection (Optional)

Check that the timestamp is within a reasonable window (e.g. 5 minutes) to guard against replay attacks:

Retry Logic

If your endpoint returns a non-2xx status or times out (10 seconds), Artmail retries:

• Retries: Up to 3 additional attempts
• Backoff: Exponential (QStash handles scheduling)
• Deduplication: Same event ID is not delivered twice concurrently

Return 200 or 204 quickly to acknowledge receipt. Process the event asynchronously if needed.

Example Webhook Handler (Node.js)

Debugging Webhooks

• Webhook Logs: View delivery attempts, status codes, and response bodies in Settings → Developer → Webhooks (click a webhook to see logs).
• Test webhook: Use the "Test" action to send a sample event to your endpoint.
• Local development: Use a tunnel (ngrok, Cloudflare Tunnel) to expose your local server for testing.

Next Steps