When you finish, your server receives a signed POST for each event you pick, and checks its signature.
Add an endpoint
- In Shopbird, open Settings > Webhooks.
- Add your endpoint's URL.
- Copy its secret. It starts with
whsec_.
Tokens can't add endpoints or read secrets. Only Settings can.
Pick events
Pick the events the endpoint gets. Each delivery's data holds IDs. Fetch the resource for its details.
| Event | Sent when |
|---|---|
lock.created |
A lock is created. |
lock.updated |
A lock changes, or is turned on or off. |
lock.deleted |
A lock is deleted. |
audience.created |
An audience is created. |
audience.updated |
An audience changes. |
audience.deleted |
An audience is deleted. |
audience_code.created |
Codes are added to an audience. |
audience_code.revoked |
Codes are revoked. |
code.redeemed |
A shopper unlocks with an audience code. See below. |
drop.created |
A drop is created. |
drop.updated |
A drop changes. |
drop.deleted |
A drop is deleted. |
drop.stage_changed |
A drop moves forward a stage. |
raffle.entered |
A shopper enters a raffle. |
raffle.drawn |
A raffle's winners are drawn. |
sync.completed |
A sync reaches Shopify. |
sync.failed |
A sync fails. Shopbird retries it. |
code.redeemed reports a signed-in customer's first unlock with a code. Their later unlocks with it are free and not reported. Each guest unlock spends a use and is reported.
Each delivery is a POST with this body. actor.type is api, admin or system.
{
"type": "lock.updated",
"timestamp": "2026-10-08T12:00:00.000Z",
"data": { "lock_id": "…", "version": 4 },
"actor": { "type": "api", "token_id": "…" }
}
Verify a signature
Shopbird signs deliveries per Standard Webhooks. Verify them with the standardwebhooks package. Answer with any 2xx within 10 seconds.
import { Webhook } from "standardwebhooks";
const webhook = new Webhook(process.env.SHOPBIRD_WEBHOOK_SECRET); // whsec_…
app.post("/webhooks/shopbird", express.raw({ type: "application/json" }), (req, res) => {
let event;
try {
event = webhook.verify(req.body.toString(), req.headers);
} catch {
return res.sendStatus(400);
}
// Deliveries can repeat: skip ones whose webhook-id you've already handled.
handle(event);
res.sendStatus(204);
});
Handle retries and duplicates
A delivery can arrive more than once. Skip one whose webhook-id header you have handled.
| Rule | Value |
|---|---|
| Success | Any 2xx within 10 seconds |
| Retries after a failure | 1 min, 5 min, 30 min, 2 h, 6 h, 12 h |
| Endpoint turned off | It answers 410, or keeps failing for 3 days. Settings says why. |
| Resend | Settings lists each endpoint's deliveries and can resend one. |
To check deliveries from a script, use a token with webhooks:read:
curl "https://app.shopbird.app/api/v1/webhook-deliveries?endpoint_id=<endpoint id>" \
-H "Authorization: Bearer sb_live_…"
import { Shopbird } from "@shopbird/sdk";
const shopbird = new Shopbird({ token: process.env.SHOPBIRD_TOKEN });
const { data } = await shopbird.webhookDeliveries.list({ endpoint_id: "<endpoint id>" });
{
"data": [
{ "event_type": "lock.updated", "status": "pending", "attempt": 2, "response_code": 500, "next_attempt_at": "…" }
],
"next_cursor": null
}
Rotate a secret
- Open Settings > Webhooks and choose Rotate secret.
- Copy the new secret. It works at once.
- Put it in your receiver within 24 hours. The old secret keeps signing alongside it until then.