Webhook Operations

An ActionBox callback is a durable, signed delivery of a terminal Action event. The delivery is queued in the same transaction as the terminal state change, so a receiver outage cannot undo a decision.

Delivery lifecycle

Status	Meaning	Your action
`pending`	Queued and waiting for a delivery attempt	Keep the receiver available.
`retrying`	A transient attempt failed and another attempt is scheduled	Fix the receiver and honor the next attempt.
`sending`	A worker currently owns the delivery lease	Do not start a parallel manual retry.
`delivered`	The receiver returned HTTP 2xx	Deduplicate the event and apply it once.
`failed`	The destination or response is permanently invalid	Fix the receiver/destination, then ask an owner or admin to retry if the delivery is retryable.

Network errors, timeouts, HTTP 429, and HTTP 5xx responses are retried with bounded backoff. Other non-2xx responses fail permanently. A valid Retry-After can postpone the next attempt. The retry window follows the plan (Developer: one day; Pro, Founder, and Team: seven days).

Delivery is at least once. Treat the event id in the JSON body as your replay key and make the handler safe if the same event arrives again. Action outcome and callback delivery are separate records: a callback failure does not change the Action's terminal state.

Inspect the queue

These endpoints require a user session, not a Source key:

curl -fsS "https://api.actionbox.cloud/v1/webhooks?environment=live&status=failed" \
  -H "Authorization: Bearer $ACTIONBOX_USER_TOKEN"

curl -fsS https://api.actionbox.cloud/v1/webhooks/summary \
  -H "Authorization: Bearer $ACTIONBOX_USER_TOKEN"

curl -fsS https://api.actionbox.cloud/v1/webhooks/<delivery_id> \
  -H "Authorization: Bearer $ACTIONBOX_USER_TOKEN"

The list supports environment=live|test|all, an optional delivery status, and a bounded limit. Detail includes the Action ID, event ID, destination scheme/host/path, attempt number, status, HTTP status, error code, timestamps, and attempt history. Query data is sanitized; the response body and callback secret are not exposed.

Retry a failed delivery

After the receiver is ready, an owner or admin can request a retry:

curl -fsS -X POST \
  https://api.actionbox.cloud/v1/webhooks/<delivery_id>/retry \
  -H "Authorization: Bearer $ACTIONBOX_USER_TOKEN"

409 WEBHOOK_IN_PROGRESS means a worker currently holds the delivery lease; read it again later. 409 WEBHOOK_NOT_RETRYABLE means the delivery was already marked delivered and cannot be replayed through this endpoint. A failed delivery can be requeued after the receiver is fixed. Do not create a new Action just to force a callback retry.

Receiver requirements

Accept a public HTTPS request without credentials in the URL.
Read the exact raw body and verify X-Actionbox-Signature using the per-Source webhook secret before parsing JSON.
Reject stale X-Actionbox-Timestamp values and compare signatures in constant time.
Persist the event ID transactionally and return a quick 2xx after accepting it. Duplicate IDs should return a safe 2xx without repeating side effects.
Keep the secret out of logs, traces, browser code, and error responses.

The signature is HMAC-SHA256 over "{timestamp}." + raw_request_body and is sent as X-Actionbox-Signature: v1=<hex>. The complete verification example is in Webhooks and callbacks.

Common delivery issues

Symptom	Likely cause	Fix
Many `retrying` deliveries	Receiver timeout, 429, or 5xx	Return a fast 2xx after durable acceptance; move slow work to a queue.
Immediate `failed` delivery	Invalid URL, redirect, credential in URL, or non-retryable response	Use a public HTTPS endpoint with no redirect or URL credential.
Receiver says “bad signature”	JSON was parsed/re-serialized before verification, wrong Source secret, or stale timestamp	Verify the original bytes and timestamp; rotate the Source webhook secret if exposure is suspected.
Event appears twice	At-least-once delivery or a manual retry	Dedupe by event `id`; do not dedupe by arrival time.
Test callback never arrives	Test-key callbacks are not delivered by the hosted production service	Inspect the test Action explicitly. Use a live Action against a controlled receiver when you need to verify callback delivery.
Callback is delivered but operation did not run	Receiver acknowledged before durable processing	Store the event before returning 2xx and reconcile failed downstream work separately.

These are application callbacks

The deliveries documented here are terminal callbacks for your Actions. They are Source-scoped and use the X-Actionbox-* headers shown above. Point this receiver only at the callback URL configured for the Action.