How to receive webhooks from your Locker

Before you start

Go to Admin, then Settings, then Integrations, and find Outbound webhooks. You need to be the owner or an admin of a Locker on an active Pro plan. Without Pro the page reads: Creating, resuming, sampling, and delivering webhooks requires an active Pro plan. You can still pause or delete existing endpoints. Pausing and deleting keep working after a downgrade, so an endpoint never keeps sending when you have lost the controls for it.

You also need a URL on the public internet that accepts an HTTPS request. Lockers refuses endpoint URLs with credentials in them, URLs that redirect, and addresses on private or internal networks. All three come back as Endpoint URL is not allowed. If nobody has written the receiving end yet, the Node example at lockers.social/api/examples/webhook-receiver.mjs already covers the parts that are easy to get wrong.

Add an endpoint

After you select Add endpoint, Lockers shows the Endpoint signing secret once. Select Copy secret, put it wherever your receiving system reads its configuration, and keep it out of source control. It starts with whsec_. The secret proves a delivery came from us and cannot call the API on its own, but anyone holding it can produce deliveries your system will trust, so store it with the same care you give the API key.

1. 1

   Enter the URL

   Enter your Endpoint URL. The placeholder, https://hooks.example.com/lockers, shows the expected format.

2. 2

   Choose a connection

   Set Named API connection (optional for public events). Leave it on No named connection for course, enrollment, completion, member, and calendar events. Choose a connection if you want invitation or post events.

3. 3

   Restrict courses if you need to

   Fill the course restrictions field if this endpoint should receive events for certain courses only. Blank means all courses, and the restriction narrows course, enrollment, and completion events only.

4. 4

   Pick the events

   Select the events you want under Events to deliver.

5. 5

   Check the permissions

   Check Endpoint permissions. Selecting an event adds the permission that event needs, and a required permission cannot be removed while its event is still selected.

6. 6

   Add the endpoint

   Select Add endpoint.

The events you can pick

Courses cover created, updated, and deleted. Enrollments cover created, updated, and deleted. Completions add a revoked event alongside created, updated, and deleted. Members cover added, updated, and removed. Calendar events cover published, updated, and removed. Invitations cover created, updated, accepted, and revoked. Post drafts cover created, updated, and deleted, with Post published as its own event.

Invitation and post events need the endpoint bound to a named connection. The note under the field reads: Endpoint permissions and courses cannot exceed its grants. An endpoint bound to a connection can deliver only what that connection's permissions allow, so if the invitation events you want are unavailable, the connection's key is missing the Invitations permission.

Send a sample first

Every endpoint row has Send sample, which delivers a clearly labeled test event to that endpoint alone. Use it before you connect anything to real activity, so you find out about a wrong path or a failing signature check while nothing depends on the answer. Sampling needs an active Pro plan, the same as live delivery.

What the receiving system has to do

Deliveries contain identifiers and small state hints. They never include member contact data or post bodies, so a delivery that reaches the wrong place or gets replayed later does not leak anything about your members. The cost is that your system asks the API when it needs the detail.

• Verify the signature with the endpoint signing secret before the body is read as anything meaningful.
• Ignore duplicates by event ID. The same delivery can arrive more than once, and a receiver that treats every arrival as new will double-count.
• Fetch the current record through the API, and treat the body as a pointer to that record.

Timeouts, retries, and order

We wait 8 seconds for a response and do not follow redirects. Any response that is not a success counts as a failure. A failed delivery is retried at 10 minutes, 30 minutes, 2 hours, and 8 hours, five attempts including the first. A receiver that answers first and does its own work afterwards is less likely to run into that timeout than one that finishes a slow job before replying.

Order is not guaranteed while an older event is still retrying. A member update from an hour ago can arrive after one from a minute ago. The body only points to the record, and reading the current state from the API tells you which version is current.

Pause, resume, and delete

Pause stops delivery to an endpoint, and Resume starts it again. Pause the endpoint before planned work on the receiving system, then resume when it is back. Resuming needs Pro; pausing does not.

Delete removes the endpoint permanently and asks: Delete this endpoint? Pending deliveries for it will no longer be sent. Anything queued for that endpoint is dropped with it, so pause the endpoint if you expect to turn it back on.

When a delivery fails

Failed deliveries appear in Failed operations. Each row offers Replay failed row, which asks: Replay this exact failed row? Delivered or processed work cannot be replayed. Replay needs an active Pro plan, and on a Locker without one the message reads: An active Pro plan is required to replay delivery.

Have the receiving system keep its own log of the events it has processed.