Subscribing to Webhooks

Synapse can send HTTP callbacks to your server when email events occur -- deliveries, opens, clicks, bounces, and more. You register a webhook endpoint in your workspace, choose which event types you want, and Synapse delivers signed payloads to your URL.

Creating an Endpoint

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_opened"],

"environment": "live"

Auth: JWT (dashboard). Requires webhooks:write permission.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Human-readable label (1--100 characters)
`url`	string	Yes	HTTPS URL that will receive POST requests
`event_types`	string[]	Yes	Which event types to subscribe to (see Event Types)
`environment`	string	No	`live` (default) or `test`

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_opened"],

"is_active": true,

"environment": "live",

"consecutive_failures": 0,

"suspended_at": null,

"created_at": "2026-04-25T10:00:00Z",

"updated_at": "2026-04-25T10:00:00Z"

"signing_secret": "whsec_a1b2c3d4e5f6..."

}

Warning

The signing_secret is returned only in the creation response. Copy and store it immediately -- you will need it to verify webhook signatures. You cannot retrieve it again.

URL Requirements

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

Event Types

Event Type	Description
`email_sent`	Email accepted by the delivery provider
`email_delivered`	Email delivered to the recipient's inbox
`email_delivery_delayed`	Temporary delivery delay (soft bounce, server busy)
`email_opened`	Recipient opened the email (pixel tracking)
`email_clicked`	Recipient clicked a link in the email
`email_bounced`	Email bounced (hard or soft)
`email_spam_reported`	Recipient marked the email as spam
`email_failed`	Email delivery permanently failed
`email_suppressed`	Email suppressed (contact on suppression list)

Updating an Endpoint

Change the name, URL, event types, or active status:

bash

curl -X PATCH https://synapse-api.pyrx.tech/v1/workspace/webhook-endpoints/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \

-H "Authorization: Bearer <jwt>" \

-H "Content-Type: application/json" \

-d '{

"event_types": ["email_delivered", "email_bounced", "email_opened", "email_clicked"],

"is_active": true

Auth: JWT (dashboard). Requires webhooks:write permission.

Re-enabling a suspended endpoint (is_active: true) resets the circuit breaker failure counter.

Deleting an Endpoint

bash

curl -X DELETE https://synapse-api.pyrx.tech/v1/workspace/webhook-endpoints/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \

-H "Authorization: Bearer <jwt>"

Returns 204 No Content. Deleting an endpoint also removes its delivery history.

Rotating the Signing Secret

If you suspect your signing secret has been compromised, rotate it:

bash

curl -X POST https://synapse-api.pyrx.tech/v1/workspace/webhook-endpoints/a1b2c3d4-e5f6-7890-abcd-ef1234567890/rotate-secret \

-H "Authorization: Bearer <jwt>"

The response includes the new signing_secret. The old secret is immediately invalidated -- update your verification code before the next delivery.

Testing an Endpoint

Send a synthetic test event to verify your endpoint is reachable and correctly verifying signatures:

bash

curl -X POST https://synapse-api.pyrx.tech/v1/workspace/webhook-endpoints/a1b2c3d4-e5f6-7890-abcd-ef1234567890/test \

-H "Authorization: Bearer <jwt>" \

-H "Content-Type: application/json" \

-d '{

"event_type": "email_delivered"

Response

json

{

"success": true,

"http_status_code": 200,

"duration_ms": 142,

"error": null

}

Test deliveries are logged with attempt_number: 0 and do not affect the circuit breaker.

Listing Endpoints

bash

curl "https://synapse-api.pyrx.tech/v1/workspace/webhook-endpoints?environment=live" \

-H "Authorization: Bearer <jwt>"

Auth: JWT (dashboard). Requires webhooks:read permission.

Returns an array of all webhook endpoints for the workspace. Optionally filter by environment (live or test).

Plan Limits

Plan	Max Webhook Endpoints
Free	2
Starter	5
Growth	15
Enterprise	Unlimited

Attempting to create an endpoint beyond your plan limit returns 403 with plan_limit_reached.