Skip to main content
POST
/
webhooks
Create a webhook endpoint
curl --request POST \
  --url https://apix.spotzee.com/api/client/webhooks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Order events to billing service",
  "url": "https://api.example.com/spotzee/webhooks",
  "event_types": [
    "delivery.delivered",
    "delivery.failed"
  ]
}
'
{
  "id": 17,
  "project_id": 42,
  "name": "Order events to billing service",
  "url": "https://api.example.com/spotzee/webhooks",
  "status": "active",
  "event_types": [
    "delivery.delivered",
    "delivery.failed"
  ],
  "has_secret": true,
  "created_at": "<string>",
  "updated_at": "<string>",
  "signing_secret": "whsec_5f6b9c4e2a8d3f1b...",
  "description": "<string>"
}

Documentation Index

Fetch the complete documentation index at: https://docs.spotzee.com/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
Authorization
string
header
required

Project-scoped secret API key (sk_…). Pass in the Authorization: Bearer <key> header. Grants access to the project the key was issued for.

Body

application/json

Create a new webhook endpoint. The plaintext signing secret is returned exactly once in the response — store it immediately; it cannot be re-fetched.

​
name
string
required

Human-readable name shown in dashboards.

Required string length: 1 - 255
Example:

"Order events to billing service"

​
url
string<uri>
required

HTTPS URL the signed event payload will be POSTed to.

Example:

"https://api.example.com/spotzee/webhooks"

​
event_types
enum<string>[]
required

Events the endpoint should subscribe to. At least one is required.

Minimum array length: 1

Event the endpoint is subscribed to. Each event identifies a queue, delivery, reputation, or infrastructure signal. See the events reference for full descriptions.

Available options:
queue.queue-message-authenticated,
queue.rescheduled,
queue.quota-exceeded,
delivery.concurrency-limit-exceeded,
delivery.attempt-start,
delivery.attempt-end,
delivery.completed,
delivery.delivered,
delivery.dsn-perm-fail,
delivery.dsn-temp-fail,
delivery.failed,
delivery.mail-from-rejected,
delivery.message-rejected,
delivery.rcpt-to-rejected,
delivery.rcpt-to-failed,
delivery.mx-lookup-failed,
delivery.ip-lookup-failed,
delivery.null-mx,
delivery.connect-error,
delivery.greeting-failed,
delivery.ehlo-rejected,
delivery.start-tls-error,
delivery.start-tls-unavailable,
delivery.implicit-tls-error,
incoming-report.abuse-report,
incoming-report.fraud-report,
incoming-report.virus-report
Example:
["delivery.delivered", "delivery.failed"]
​
description
string | null

Optional free-text note describing the endpoint.

​
signing_secret
string

Optional caller-supplied signing secret. If omitted, a cryptographically random secret is generated and returned in the response. Marked writeOnly — never echoed back on subsequent reads.

Required string length: 16 - 256
Example:

"whsec_5f6b9c4e2a8d3f1b..."

Response

The newly created webhook endpoint, including the one-time plaintext signing secret.

Webhook endpoint plus the one-time-visible plaintext signing secret. Returned only by POST /webhooks and POST /webhooks/{endpointId}/rotate-secret. Subsequent reads omit the plaintext; only has_secret: true/false is exposed.

​
id
integer
required

Numeric webhook endpoint identifier.

Example:

17

​
project_id
integer
required

Identifier of the owning project.

Example:

42

​
name
string
required

Human-readable name shown in dashboards.

Example:

"Order events to billing service"

​
url
string<uri>
required

HTTPS URL the signed event payload will be POSTed to.

Example:

"https://api.example.com/spotzee/webhooks"

​
status
enum<string>
required

Lifecycle state of the endpoint. active receives events; inactive is paused by the user; disabled was suspended by the system after repeated delivery failures.

Available options:
active,
inactive,
disabled
Example:

"active"

​
event_types
enum<string>[]
required

Events the endpoint is subscribed to.

Event the endpoint is subscribed to. Each event identifies a queue, delivery, reputation, or infrastructure signal. See the events reference for full descriptions.

Available options:
queue.queue-message-authenticated,
queue.rescheduled,
queue.quota-exceeded,
delivery.concurrency-limit-exceeded,
delivery.attempt-start,
delivery.attempt-end,
delivery.completed,
delivery.delivered,
delivery.dsn-perm-fail,
delivery.dsn-temp-fail,
delivery.failed,
delivery.mail-from-rejected,
delivery.message-rejected,
delivery.rcpt-to-rejected,
delivery.rcpt-to-failed,
delivery.mx-lookup-failed,
delivery.ip-lookup-failed,
delivery.null-mx,
delivery.connect-error,
delivery.greeting-failed,
delivery.ehlo-rejected,
delivery.start-tls-error,
delivery.start-tls-unavailable,
delivery.implicit-tls-error,
incoming-report.abuse-report,
incoming-report.fraud-report,
incoming-report.virus-report
Example:
["delivery.delivered", "delivery.failed"]
​
has_secret
boolean
required

Whether a signing secret is currently configured. The plaintext secret itself is only returned on create and on rotate — never re-fetched.

​
created_at
string | null
required

Time the endpoint was created. ISO 8601.

​
updated_at
string | null
required

Time the endpoint was last modified. ISO 8601.

​
signing_secret
string
required

Plaintext signing secret. Returned exactly once — store it securely now. Use this value as the HMAC key when verifying Spotzee-Signature on inbound deliveries.

Example:

"whsec_5f6b9c4e2a8d3f1b..."

​
description
string | null

Optional free-text note describing the endpoint.