Webhook endpoints

Overview

A webhook endpoint is a URL on your server. When a job finishes, the API sends an event to every enabled endpoint of the account. An account can have up to 10 endpoints. Endpoints can also be managed in the dashboard.

• Endpoints belong to the account, not to a key or a mode. An endpoint receives the events of live jobs and of test jobs. Each event says which with livemode.
• Each endpoint has its own secret, which signs the deliveries to that endpoint. It is shown once, when the endpoint is created, and once more each time it is rotated.
• A job can also name a webhook_url of its own. Deliveries to that URL are signed with a different secret: the account's signing secret, described below.

See Webhooks for how to receive and verify an event.

The webhook endpoint object

{
  "id": "whk_R4tYp9LmXc2VbN7qWz0K",
  "object": "webhook_endpoint",
  "url": "https://example.com/hooks/smol",
  "enabled": true,
  "created_at": "2026-10-01T09:30:12.480Z"
}

Create an endpoint

Send a JSON body. A field that is not listed here is refused with bad_request.

curl -X POST "https://api.smolmac.com/v1/webhook_endpoints" \
  -H "Authorization: Bearer $SMOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hooks/smol"}'

The response has status 201. It is the endpoint object with one more field, secret.

{
  "id": "whk_R4tYp9LmXc2VbN7qWz0K",
  "object": "webhook_endpoint",
  "url": "https://example.com/hooks/smol",
  "enabled": true,
  "created_at": "2026-10-01T09:30:12.480Z",
  "secret": "whsec_h2Kd8LqT5xZc1VbN9mWp3RyA7sJf0GuE"
}

The secret is whsec_ followed by 32 letters and digits. The same URL can be registered more than once. Each registration is a separate endpoint with its own secret and receives its own delivery.

List endpoints

Returns every endpoint of the account, newest first. The list is not paginated, so has_more is always false. Secrets are not included.

curl "https://api.smolmac.com/v1/webhook_endpoints" \
  -H "Authorization: Bearer $SMOL_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "whk_R4tYp9LmXc2VbN7qWz0K",
      "object": "webhook_endpoint",
      "url": "https://example.com/hooks/smol",
      "enabled": true,
      "created_at": "2026-10-01T09:30:12.480Z"
    }
  ],
  "has_more": false
}

Pause or resume an endpoint

Send a JSON body with one field. A field that is not listed here is refused with bad_request.

curl -X PATCH "https://api.smolmac.com/v1/webhook_endpoints/whk_R4tYp9LmXc2VbN7qWz0K" \
  -H "Authorization: Bearer $SMOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled":false}'

{
  "id": "whk_R4tYp9LmXc2VbN7qWz0K",
  "object": "webhook_endpoint",
  "url": "https://example.com/hooks/smol",
  "enabled": false,
  "created_at": "2026-10-01T09:30:12.480Z"
}

• A paused endpoint keeps its id, its URL and its secret.
• Jobs that finish while the endpoint is paused send it nothing, and those events are not sent later, when it is resumed.
• Deliveries that were already queued for a job that finished before the pause, including their retries, are still attempted.
• The URL of an endpoint cannot be changed. To use another URL, create a new endpoint and delete the old one.

Rotate the secret

Gives the endpoint a new secret. The request has no body. The response is the endpoint object with the new secret, which is shown only here.

curl -X POST "https://api.smolmac.com/v1/webhook_endpoints/whk_R4tYp9LmXc2VbN7qWz0K/rotate_secret" \
  -H "Authorization: Bearer $SMOL_API_KEY"

{
  "id": "whk_R4tYp9LmXc2VbN7qWz0K",
  "object": "webhook_endpoint",
  "url": "https://example.com/hooks/smol",
  "enabled": true,
  "created_at": "2026-10-01T09:30:12.480Z",
  "secret": "whsec_Lm3Xc7VbN1qWz9RtY5pKd2HsF8gJ0aEu"
}

• Events for jobs that finish after the call are signed with the new secret. The old secret is not used for them, and there is no period in which both sign.
• A delivery that was queued before the call keeps the secret it was queued with, on every retry. Retries can run for about 21 hours.
• So have your receiver accept both secrets while you switch: deploy the new one next to the old, and remove the old one a day later.
• The account signing secret, which signs deliveries to a job's webhook_url, cannot be rotated with this request.

Send a test event

Sends one event of type ping to the endpoint, signed with its secret, and answers with what the endpoint returned. Use it to check your signature verification without running a job. The request has no body.

curl -X POST "https://api.smolmac.com/v1/webhook_endpoints/whk_R4tYp9LmXc2VbN7qWz0K/test" \
  -H "Authorization: Bearer $SMOL_API_KEY"

{
  "object": "webhook_test",
  "event_id": "evt_Tq6Wn1YdK8sLc3VbX0mR",
  "delivered": true,
  "status": 204,
  "duration_ms": 182
}

• The request itself answers 200 whether or not the delivery worked. Read delivered.
• The event is sent once and is not retried. Redirects are not followed.
• The event's livemode is true when you call with a live key and false with a test key.
• A paused endpoint can be tested. The test does not resume it.

Delete an endpoint

Deletes the endpoint. Jobs that finish from now on send it nothing. Deliveries that were already queued for a job that finished earlier, including their retries, are still attempted.

curl -X DELETE "https://api.smolmac.com/v1/webhook_endpoints/whk_R4tYp9LmXc2VbN7qWz0K" \
  -H "Authorization: Bearer $SMOL_API_KEY"

{
  "id": "whk_R4tYp9LmXc2VbN7qWz0K",
  "object": "webhook_endpoint",
  "deleted": true
}

Returns 404 not_found if the account has no endpoint with that id.

Get the signing secret

Returns the account's signing secret. It signs deliveries to a URL given in a job's webhook_url, when that URL is not one of your registered endpoints. There is one such secret per account. It is created the first time it is needed, and this request returns the same value every time after that.

curl "https://api.smolmac.com/v1/webhook_endpoints/signing_secret" \
  -H "Authorization: Bearer $SMOL_API_KEY"

{
  "object": "webhook_signing_secret",
  "secret": "whsec_Qe7Zr2MnB5vXc8LkJ1hGf4DsA9pWy0Tu"
}

Errors