Skip to content

Outbound Webhooks Guide

Synapse can send real-time event notifications to your application via outbound webhooks. When an email is delivered, opened, clicked, or bounces, Synapse sends an HTTP POST to your configured endpoint with event details.

Note

This guide covers outbound webhooks -- events Synapse sends to your server. For inbound webhooks that Synapse receives from external services (Resend, Lemon Squeezy), see Webhook Events.

How It Works

  1. You register a webhook endpoint URL with the event types you want to receive
  2. When a matching event occurs, Synapse sends an HTTPS POST with a JSON payload
  3. Your server verifies the HMAC-SHA256 signature and processes the event
  4. If delivery fails, Synapse retries with exponential backoff (10s, 30s, 120s)

Supported Event Types

Event TypeDescription
email_sentEmail was submitted to the delivery provider
email_deliveredEmail was accepted by the recipient's mail server
email_delivery_delayedDelivery was temporarily delayed
email_openedRecipient opened the email (pixel tracking)
email_clickedRecipient clicked a link in the email
email_bouncedEmail bounced (hard or soft)
email_spam_reportedRecipient marked the email as spam
email_failedEmail delivery permanently failed
email_suppressedEmail was suppressed (unsubscribed, NLT required modifier)

Creating a Webhook Endpoint

curl

bash
curl -X POST https://synapse-api.pyrx.tech/v1/workspace/webhook-endpoints \
-H "Authorization: Bearer <jwt>" \
-H "Content-Type: application/json" \
-d '{
"name": "Order notifications",
"url": "https://example.com/webhooks/synapse",
"event_types": ["email_delivered", "email_bounced", "email_clicked"],
"environment": "live"
}'

Response (201 Created)

json
{
"endpoint": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Order notifications",
"url": "https://example.com/webhooks/synapse",
"event_types": ["email_delivered", "email_bounced", "email_clicked"],
"is_active": true,
"environment": "live",
"consecutive_failures": 0,
"suspended_at": null,
"created_at": "2026-05-06T10:00:00Z",
"updated_at": "2026-05-06T10:00:00Z"
},
"signing_secret": "whsec_a1b2c3d4e5f67890..."
}
Danger

The signing_secret is only shown once at creation time. Save it immediately in your application's environment variables. You will need it to verify webhook signatures.

URL Requirements

  • Must use HTTPS (HTTP is rejected)
  • Must not target private or internal networks (localhost, 10.x, 172.16.x, 192.168.x, metadata endpoints)
  • Must respond within 10 seconds

Webhook Payload

Every webhook delivery is an HTTPS POST with a JSON body:

json
{
"event_type": "email_delivered",
"event_id": "evt_8f14e45f-ceea-467f-a83c-01a01ba3c5db",
"timestamp": "2026-05-06T10:15:30Z",
"data": {
"email_log_id": "el_abc123",
"contact_id": "c1d2e3f4-5678-90ab-cdef-1234567890ab",
"external_id": "user_12345",
"email": "[email protected]",
"template_slug": "order-confirmation",
"flow_id": "f1a2b3c4-5678-90ab-cdef-1234567890ab"
}
}

Signature Headers

Every delivery includes these headers for verification:

HeaderDescription
X-Synapse-SignatureHMAC-SHA256 signature of the request body
X-Synapse-TimestampUnix timestamp when the webhook was sent
X-Synapse-Event-TypeThe event type (e.g., email_delivered)

Verifying Signatures

Always verify the HMAC-SHA256 signature before processing a webhook. This prevents forgery attacks.

Python

python
import hashlib
import hmac
import time
 
SIGNING_SECRET = "whsec_a1b2c3d4e5f67890..."
 
def verify_webhook(request_body: bytes, signature: str, timestamp: str) -> bool:
# Reject if timestamp is older than 5 minutes (replay protection)
if abs(time.time() - int(timestamp)) > 300:
return False
 
# Compute expected signature
signed_payload = f"{timestamp}.{request_body.decode()}"
expected = hmac.new(
SIGNING_SECRET.encode(),
signed_payload.encode(),
hashlib.sha256,
).hexdigest()
 
return hmac.compare_digest(expected, signature)

JavaScript (Node.js)

javascript
const crypto = require("crypto");
 
const SIGNING_SECRET = "whsec_a1b2c3d4e5f67890...";
 
function verifyWebhook(body, signature, timestamp) {
// Reject if timestamp is older than 5 minutes
if (Math.abs(Date.now() / 1000 - parseInt(timestamp)) > 300) {
return false;
}
 
const signedPayload = `${timestamp}.${body}`;
const expected = crypto
.createHmac("sha256", SIGNING_SECRET)
.update(signedPayload)
.digest("hex");
 
return crypto.timingSafeEqual(
Buffer.from(expected),
Buffer.from(signature)
);
}

Retry Policy

If your endpoint returns a non-2xx status code or times out, Synapse retries with exponential backoff:

AttemptDelayTotal elapsed
1st retry10 seconds10s
2nd retry30 seconds40s
3rd retry120 seconds160s

After 3 failed attempts, the delivery is marked as failed. If an endpoint accumulates 10 consecutive failures, it is automatically suspended and stops receiving deliveries.

Resuming a Suspended Endpoint

If an endpoint is suspended, fix the underlying issue (server error, DNS, firewall) and then re-activate it via the API or dashboard. Past failed deliveries are not replayed -- only new events are sent after reactivation.

Managing Endpoints

List Endpoints

bash
curl https://synapse-api.pyrx.tech/v1/workspace/webhook-endpoints \
-H "Authorization: Bearer <jwt>"

Update an Endpoint

bash
curl -X PATCH https://synapse-api.pyrx.tech/v1/workspace/webhook-endpoints/{id} \
-H "Authorization: Bearer <jwt>" \
-H "Content-Type: application/json" \
-d '{
"event_types": ["email_delivered", "email_bounced"],
"is_active": true
}'

Delete an Endpoint

bash
curl -X DELETE https://synapse-api.pyrx.tech/v1/workspace/webhook-endpoints/{id} \
-H "Authorization: Bearer <jwt>"

Rotate Signing Secret

bash
curl -X POST https://synapse-api.pyrx.tech/v1/workspace/webhook-endpoints/{id}/rotate-secret \
-H "Authorization: Bearer <jwt>"

The response includes the new signing_secret. Update your server immediately -- the old secret becomes invalid.

Test an Endpoint

Send a synthetic test event to verify your endpoint is working:

bash
curl -X POST https://synapse-api.pyrx.tech/v1/workspace/webhook-endpoints/{id}/test \
-H "Authorization: Bearer <jwt>" \
-H "Content-Type: application/json" \
-d '{"event_type": "email_delivered"}'

View Delivery History

bash
curl "https://synapse-api.pyrx.tech/v1/workspace/webhook-endpoints/{id}/deliveries?limit=20" \
-H "Authorization: Bearer <jwt>"

Best Practices

  1. Always verify signatures -- never process unverified webhook payloads
  2. Respond quickly -- return 200 within 10 seconds, then process asynchronously
  3. Handle duplicates -- use event_id for idempotent processing
  4. Monitor delivery history -- check for consecutive failures before they trigger suspension
  5. Use test mode -- create endpoints in the test environment first to validate your handler
  6. Store the signing secret securely -- treat it like an API key (environment variable, secret manager)