Docs

Receive webhooks

Get a signed POST when locks, audiences, codes, drops or syncs change.

When you finish, your server receives a signed POST for each event you pick, and checks its signature.

Add an endpoint

  1. In Shopbird, open Settings > Webhooks.
  2. Add your endpoint's URL.
  3. 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_…"
{
  "data": [
    { "event_type": "lock.updated", "status": "pending", "attempt": 2, "response_code": 500, "next_attempt_at": "…" }
  ],
  "next_cursor": null
}

Rotate a secret

  1. Open Settings > Webhooks and choose Rotate secret.
  2. Copy the new secret. It works at once.
  3. Put it in your receiver within 24 hours. The old secret keeps signing alongside it until then.