API reference · Events and webhooks

Webhooks

Get a signed message the moment something changes. Manage the address, the secret and the delivery log.

get/webhookWebhook status
put/webhookSet the webhook address
delete/webhookTurn webhooks off
post/webhook/testSend a test event
post/webhook/rotateRotate the signing secret
post/webhook/resumeResume a paused webhook
get/webhook/deliveriesDelivery log
post/webhook/deliveries/{id}/retryRetry a delivery

get/webhook

Webhook status

Businesses only

The address we send events to, whether it is paused, and delivery counts. The signing secret is never readable.

Response 200

In data:

urlstring · nullable
hasSecretboolean
pausedAtdate-time · nullable
ISO 8601 date-time.
failuresinteger
Deliveries in a row that gave up.
countsobject
Show 4 fields
- deliveredinteger
- failedinteger
- queuedinteger
- heldinteger

Errors

401unauthorized: the API key is missing, wrong or revoked.
403forbidden: this key may not do that (wrong plan, not a business, or the account is not approved).

curl "https://engine-production-0004.up.railway.app/api/v1/webhook" \
  -H "Authorization: Bearer wc_test_YOUR_KEY"

put/webhook

Set the webhook address

Businesses only

Public https addresses only (private networks are refused, now and at every delivery). The first time, the response carries the signing secret (whsec_…): copy it, it is shown once.

Request body · application/json

urlstringrequired

Response 200

In data:

urlstring
secretstring
Only the first time.
notestring

Errors

400invalid: something in the request is wrong. The message says what.
401unauthorized: the API key is missing, wrong or revoked.
403forbidden: this key may not do that (wrong plan, not a business, or the account is not approved).

curl -X PUT "https://engine-production-0004.up.railway.app/api/v1/webhook" \
  -H "Authorization: Bearer wc_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://alpha.example/hooks/waca"
}'

Response · 200

{
  "data": {
    "url": "https://alpha.example/hooks/waca",
    "secret": "whsec_MfKQ9r8GsBn…",
    "note": "Copy this signing secret now. It will not be shown again."
  }
}

delete/webhook

Turn webhooks off

Businesses only

Events are still recorded; read them with GET /events.

Response 200

The response body

okboolean

Errors

401unauthorized: the API key is missing, wrong or revoked.
403forbidden: this key may not do that (wrong plan, not a business, or the account is not approved).

curl -X DELETE "https://engine-production-0004.up.railway.app/api/v1/webhook" \
  -H "Authorization: Bearer wc_test_YOUR_KEY"

post/webhook/test

Send a test event

Businesses only

Sends a webhook.test event now and tells you how your server answered.

Response 200

In data:

statusstring
httpStatusinteger · nullable
errorstring · nullable
attemptsinteger

Errors

401unauthorized: the API key is missing, wrong or revoked.
403forbidden: this key may not do that (wrong plan, not a business, or the account is not approved).
409conflict or unavailable: not possible in the current state, or the car was just taken.

curl -X POST "https://engine-production-0004.up.railway.app/api/v1/webhook/test" \
  -H "Authorization: Bearer wc_test_YOUR_KEY"

post/webhook/rotate

Rotate the signing secret

Businesses only

A new secret, shown once. The old one stops working immediately.

Response 201

In data:

secretstring
notestring

Errors

401unauthorized: the API key is missing, wrong or revoked.
403forbidden: this key may not do that (wrong plan, not a business, or the account is not approved).
409conflict or unavailable: not possible in the current state, or the car was just taken.

curl -X POST "https://engine-production-0004.up.railway.app/api/v1/webhook/rotate" \
  -H "Authorization: Bearer wc_test_YOUR_KEY"

post/webhook/resume

Resume a paused webhook

Businesses only

After three deliveries in a row give up, the webhook is paused (and you are emailed). Events are held, not lost. Fix your server, then resume: everything held is sent.

Response 200

In data:

releasedinteger
How many held events were queued.

Errors

401unauthorized: the API key is missing, wrong or revoked.
403forbidden: this key may not do that (wrong plan, not a business, or the account is not approved).

curl -X POST "https://engine-production-0004.up.railway.app/api/v1/webhook/resume" \
  -H "Authorization: Bearer wc_test_YOUR_KEY"

get/webhook/deliveries

Delivery log

Businesses only

Each attempt to reach your server: what we sent, how it answered and whether we will retry.

Query parameters

statusstring
queued, delivered, failed or held.
queueddeliveredfailedheld
eventstring
Only this event type.
pageinteger
Page number, from 1.
Example: 1
limitinteger
Items per page (1–100). Default 20.
Example: 20

Response 200

A page: { data: [ … ], page, totalPages, total }. Each item in data:

idinteger
eventIdstring
eventstring
referencestring · nullable
livemodeboolean
statusenum
queueddeliveredfailedheld
attemptsinteger
lastStatusCodeinteger · nullable
lastErrorstring · nullable
nextAttemptAtdate-time · nullable
ISO 8601 date-time.
deliveredAtdate-time · nullable
ISO 8601 date-time.
createdAtdate-time
ISO 8601 date-time.

Errors

401unauthorized: the API key is missing, wrong or revoked.
403forbidden: this key may not do that (wrong plan, not a business, or the account is not approved).

curl "https://engine-production-0004.up.railway.app/api/v1/webhook/deliveries?page=1&limit=20" \
  -H "Authorization: Bearer wc_test_YOUR_KEY"

post/webhook/deliveries/{id}/retry

Retry a delivery

Businesses only

Sends it again with the same body and event id.

Path parameters

idintegerrequired
The delivery id.
Example: 118

Response 200

In data:

statusstring
httpStatusinteger · nullable
errorstring · nullable

Errors

401unauthorized: the API key is missing, wrong or revoked.
403forbidden: this key may not do that (wrong plan, not a business, or the account is not approved).
404not_found: no such thing, or it is not yours.
409conflict or unavailable: not possible in the current state, or the car was just taken.

curl -X POST "https://engine-production-0004.up.railway.app/api/v1/webhook/deliveries/118/retry" \
  -H "Authorization: Bearer wc_test_YOUR_KEY"