Delivery, Retries & Management

This page covers how TakeTheme delivers webhooks — the request it sends, how failures are retried, when endpoints are auto-disabled — and how to manage your endpoints via the API.

The delivery request

Each event is delivered as an HTTP POST with a JSON body (the envelope) and the following headers:

Header	Example	Description
Content-Type	application/json	The body is always JSON.
X-TakeTheme-Signature	t=1751371200,v1=5257a8…	HMAC signature — see Verifying Signatures.
X-TakeTheme-Event	order.paid	The event type. Matches the envelope's type.
X-TakeTheme-Delivery	3f1c2b9e-8a4d-…	Unique delivery/event ID. Matches the envelope's id. Deduplicate on this.
User-Agent	TakeTheme-Webhooks/1.0	Identifies TakeTheme's delivery agent.

What counts as success

• Success: your endpoint responds with any 2xx status within 10 seconds.
• Failure: any non-2xx status, a timeout, a connection error, or a redirect (3xx responses are not followed).

Respond as soon as you've safely received the event — acknowledge with 200, then process asynchronously. Doing slow work before responding risks a timeout and unnecessary retries.

Retries

If a delivery fails, TakeTheme retries with exponential backoff and jitter, up to 8 total attempts. Before the n-th attempt (for n ≥ 2; attempt 1 is the initial delivery) TakeTheme waits 30s × 4^(n-1), capped at 6 hours, with ±15% random jitter:

Attempt	Approx. delay after previous	Approx. time since first attempt
1	—	0
2	~2 minutes	~2 minutes
3	~8 minutes	~10 minutes
4	~32 minutes	~42 minutes
5	~2.1 hours	~2.8 hours
6	~6 hours (capped)	~8.8 hours
7	~6 hours	~14.8 hours
8	~6 hours	~20.8 hours

After the 8th attempt fails, the delivery is marked exhausted and no longer retried automatically. You can replay exhausted deliveries once your endpoint is healthy.

Idempotency

Because a slow-but-eventually-successful response can still trigger a retry, the same event may be delivered more than once. Deduplicate on the X-TakeTheme-Delivery header (equal to the envelope id) so reprocessing is a no-op.

Automatic disabling

To protect chronically broken endpoints from generating endless traffic, TakeTheme auto-disables an endpoint after 3 exhausted deliveries within a 7-day window. When this happens:

• The endpoint's isActive is set to false and it stops receiving events.
• A failure notification email is sent to the store owner.

Re-enable the endpoint (via the Dashboard or a PATCH setting isActive: true) once you've fixed the underlying problem, then optionally replay the deliveries you missed.

Delivery logs

Every delivery attempt is recorded. Fetch the recent logs for an endpoint to debug failures:

curl -X GET "https://api.taketheme.com/api/v1/store/webhooks/endpoints/{id}/logs?page=1&limit=20" \
  -H "tt-api-key: tt_xxx"

Each log entry includes:

Field	Description
eventType	The event that was delivered.
eventId	The delivery/event ID.
status	pending, success, failed, or exhausted.
attempt	Which attempt this record reflects.
httpStatus	The HTTP status your endpoint returned (0 for a network/timeout error).
responseBody	The first 1 KB of your endpoint's response body.
errorMessage	Error detail when delivery failed (timeout, DNS, TLS, blocked host…).
nextRetryAt	When the next attempt is scheduled (for failed records still retrying).
deliveredAt	When delivery succeeded (for success).

Managing endpoints

Endpoints can be managed from the Dashboard (Settings → Webhooks) or via the REST API below. All endpoints are under:

https://api.taketheme.com/api/v1/store/webhooks

Requests authenticate with your tt-api-key (or a Dashboard session) and require store-settings access. Your plan must include webhook access (canAccessWebhooks), otherwise these return 403.

Endpoint limit

A store may have at most 5 webhook endpoints. Delete unused endpoints before creating new ones.

List endpoints

curl -X GET "https://api.taketheme.com/api/v1/store/webhooks/endpoints?page=1&limit=20" \
  -H "tt-api-key: tt_xxx"

Returns your endpoints with the signing secret omitted.

Create an endpoint

curl -X POST "https://api.taketheme.com/api/v1/store/webhooks/endpoints" \
  -H "tt-api-key: tt_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/taketheme",
    "events": ["order.placed", "order.paid"],
    "description": "Production order sync",
    "metadata": { "team": "fulfillment" }
  }'

Body field	Required	Notes
url	yes	Must be https://. Internal/private hosts are rejected.
events	yes	Non-empty array of event types.
description	no	Up to 256 characters.
metadata	no	Arbitrary string→string key/value pairs for your own bookkeeping.

Returns 201 with the endpoint and a one-time secret (whsec_…). Store it now — it's never shown again.

Get an endpoint

curl -X GET "https://api.taketheme.com/api/v1/store/webhooks/endpoints/{id}" \
  -H "tt-api-key: tt_xxx"

Update an endpoint

Change the URL, subscribed events, description, or enable/disable it:

curl -X PATCH "https://api.taketheme.com/api/v1/store/webhooks/endpoints/{id}" \
  -H "tt-api-key: tt_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["order.placed", "order.paid", "order.fulfilled"],
    "isActive": true
  }'

Delete an endpoint

curl -X DELETE "https://api.taketheme.com/api/v1/store/webhooks/endpoints/{id}" \
  -H "tt-api-key: tt_xxx"

Returns 204 No Content.

Rotate the signing secret

curl -X POST "https://api.taketheme.com/api/v1/store/webhooks/endpoints/{id}/rotate-secret" \
  -H "tt-api-key: tt_xxx"

Returns a new secret (shown once) and invalidates the old one immediately. See Rotating the signing secret.

Replaying exhausted deliveries

Re-queue every delivery for an endpoint that reached the exhausted state — useful after fixing an outage:

curl -X POST "https://api.taketheme.com/api/v1/store/webhooks/endpoints/{id}/replay-exhausted" \
  -H "tt-api-key: tt_xxx"

{ "replayed": 12 }

Replayed deliveries re-enter the normal delivery pipeline (with fresh retries). Make sure the endpoint is active and healthy first.

Best practices

• Verify every request. Reject anything that fails signature verification. See Verifying Signatures.
• Acknowledge fast, process later. Return 2xx within a couple of seconds; hand off slow work to a queue.
• Be idempotent. Deduplicate on X-TakeTheme-Delivery. Retries and replays can deliver the same event more than once.
• Don't assume ordering. Reconcile from the payload's status fields rather than the sequence of arrivals.
• Monitor your logs. Check delivery logs (or your own request logs) for repeated failures before you hit the auto-disable threshold.
• Subscribe narrowly. Only subscribe to the events you actually handle to reduce load on your endpoint.