Webhooks
Webhooks notify an external system in real time when something happens in your store — an order is placed, paid, fulfilled, cancelled, and more. Instead of that system constantly asking TakeTheme "has anything changed?", TakeTheme pushes a message the moment it does.
Use them to keep an ERP, accounting tool, warehouse/3PL, CRM, or a custom internal dashboard in sync with your store automatically.
Manage webhooks from Settings → Webhooks.
Webhooks are available on plans that include developer/webhook access. If your plan doesn't include them, the Webhooks tab prompts you to upgrade. Check your plan on the Dashboard billing page.
Setting up a webhook means pointing TakeTheme at a URL on a server you or your developer control that can receive and verify the messages. If you just want automated customer emails (order confirmations, abandoned cart, review requests), you want Marketing Automations instead — no code required.
The Webhooks page
The Settings → Webhooks page gives you an at-a-glance view of every endpoint:
- Stats cards — total endpoints (out of your limit of 5), plus how many are Active, Failing, or Disabled.
- Search & filters — find an endpoint by URL, description, or event, and filter by All / Active / Disabled.
- Endpoint cards — each shows the destination URL (with a one-click copy button), a status badge, the subscribed events, when it was created, when it last delivered successfully, and a failure count if it's struggling.
Status badges
| Badge | Meaning |
|---|---|
| Active | Healthy — receiving events and delivering successfully. |
| Failing | Still active, but recent deliveries have failed. Investigate before it's disabled. |
| Disabled | Not receiving events — either you turned it off or TakeTheme auto-disabled it after repeated failures. |
Creating an endpoint
- Go to Settings → Webhooks and click Create webhook (top right). If you've reached the limit of 5 endpoints, delete an unused one first.
- Fill in the form:
- Endpoint URL (required) — the HTTPS address that will receive events, e.g.
https://example.com/webhooks/taketheme. Plainhttp://URLs are rejected; the address must be publicly reachable (internal/private addresses are blocked). - Events (required) — pick which events this endpoint should receive. Select at least one.
- Description (optional) — a note for your team, e.g. "Warehouse fulfillment sync".
- Endpoint URL (required) — the HTTPS address that will receive events, e.g.
- Click Create.
Save your signing secret
Right after you create an endpoint, TakeTheme shows a signing secret (starts with whsec_…). Your receiving server uses it to verify that incoming messages genuinely came from TakeTheme.
The signing secret is displayed once, at creation (and again only if you rotate it). Copy it and store it somewhere safe. If you lose it, you'll need to rotate to get a new one.
Events you can subscribe to
| Event | Sent when… |
|---|---|
order.placed | A new order is created. |
order.paid | An order is paid / payment is captured. |
order.fulfilled | An order is marked fulfilled. |
order.cancelled | An order is cancelled. |
order.returned | An order is marked returned. |
order.refunded | An order is refunded. |
order.updated | An order is edited or its status is reconciled. |
Subscribe only to the events the receiving system actually handles. For the exact data each event carries, see the Events Reference.
Managing an endpoint
Each endpoint card has these actions:
| Action | What it does |
|---|---|
| View logs | Open the delivery history (see below). |
| Edit | Change the URL, subscribed events, or description, and toggle the endpoint active/inactive. |
| Rotate secret | Generate a new signing secret. The old one stops working immediately — update your server promptly. |
| Enable / Disable | Pause or resume delivery without deleting the endpoint. |
| Delete | Remove the endpoint permanently. |
Delivery logs
Click View logs on any endpoint to see its recent delivery attempts. Each row shows:
- Event — which event was sent (e.g.
order.paid). - Status —
success,failed,pending, orexhausted. - Attempt — which retry this was (e.g.
3 / 8). - HTTP — the status code your server returned (
—for a timeout or connection error). - Time — when the attempt was made.
Expand a row to see the error message, your server's response body, and the exact payload that was sent — invaluable when debugging why a delivery failed.
Use Refresh to reload, and Replay exhausted to re-send every delivery that permanently failed (the button shows how many are waiting). Fix the problem on your server first, then replay.
Delivery logs are kept for a limited window and are meant for recent troubleshooting, not long-term auditing.
When deliveries fail
TakeTheme expects your endpoint to reply with a success response within about 10 seconds. If it doesn't (server down, error, or too slow), TakeTheme automatically retries with increasing gaps — up to 8 attempts spread over roughly a day.
If an endpoint keeps failing (three deliveries exhaust all their retries within a week), TakeTheme auto-disables it to avoid hammering a broken server, and emails you so you know. Once you've fixed the problem:
- Edit the endpoint and switch it back on (or use Enable).
- Open View logs and click Replay exhausted to re-send what was missed.
For the full retry schedule and the technical detail behind auto-disable, see Delivery, Retries & Management.
For your developer
The receiving side is a developer task. Point them to the API Guide:
- Webhooks Overview — how delivery works and a receiver quick start.
- Verifying Signatures — validate authenticity (with Node, Python, PHP, Ruby, and Go examples).
- Events Reference — the payload of every event.
- Delivery, Retries & Management — headers, retries, logs, and the management API.
Everything on this page can also be done programmatically via the management API under https://api.taketheme.com/api/v1/store/webhooks — see the Delivery & Management reference.
FAQ
How many endpoints can I create? Up to 5 per store. Delete unused ones to make room.
My endpoint shows "Failing" — what should I do? Recent deliveries failed. Open View logs, expand a failed row to read the error and your server's response, and fix the issue before it's auto-disabled.
I lost my signing secret. Can I see it again? No — it's shown only once. Click Rotate secret to generate a new one, then update it on your server.
Do webhooks send customer emails? No. Webhooks send data to another system. For automated emails to customers, use Marketing Automations.
Can the same event arrive twice? Occasionally, yes — for example if your server was slow to respond and TakeTheme retried. Your developer should make the receiver handle duplicates safely (deduplicate on the delivery ID).