Webhook Endpoints API
Register and manage outbound webhook endpoints that receive email event notifications from Synapse.
For a guide on setting up webhooks, see Subscribing to Webhooks. For event payload details, see Event Types & Payloads.
Authentication
All webhook endpoint management requires JWT authentication (dashboard session) with webhooks:read or webhooks:write permissions.
Endpoints
| Method | Path | Description |
|---|---|---|
GET | /v1/workspace/webhook-endpoints | List all webhook endpoints |
POST | /v1/workspace/webhook-endpoints | Create a webhook endpoint |
PATCH | /v1/workspace/webhook-endpoints/{id} | Update a webhook endpoint |
DELETE | /v1/workspace/webhook-endpoints/{id} | Delete a webhook endpoint |
POST | /v1/workspace/webhook-endpoints/{id}/rotate-secret | Rotate the signing secret |
POST | /v1/workspace/webhook-endpoints/{id}/test | Send a test delivery |
GET | /v1/workspace/webhook-endpoints/{id}/deliveries | List delivery history |
Create Endpoint
POST /v1/workspace/webhook-endpoints
Permission: webhooks:write
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 | Event types to subscribe to |
environment | string | No | live (default) or test |
Response (201 Created)
The signing_secret is returned only in the creation response. Store it securely -- you cannot retrieve it again.
Update Endpoint
PATCH /v1/workspace/webhook-endpoints/{id}
Permission: webhooks:write
Update the name, URL, event types, or active status. Re-enabling a suspended endpoint resets the failure counter.
Rotate Secret
POST /v1/workspace/webhook-endpoints/{id}/rotate-secret
Permission: webhooks:write
Generates a new signing secret. The old secret is immediately invalidated.
Test Delivery
POST /v1/workspace/webhook-endpoints/{id}/test
Permission: webhooks:write
Sends a synthetic test event to verify your endpoint is reachable.
Delivery History
GET /v1/workspace/webhook-endpoints/{id}/deliveries
Permission: webhooks:read
Returns a paginated list of delivery attempts with status, HTTP response code, duration, and error details.
| Parameter | Type | Default | Description |
|---|---|---|---|
status_filter | string | (all) | Filter by success or failed |
limit | integer | 20 | Max items per page (max 100) |
offset | integer | 0 | Pagination offset |
Plan Limits
| Plan | Max Webhook Endpoints |
|---|---|
| Free | 2 |
| Starter | 5 |
| Growth | 15 |
| Enterprise | Unlimited |