Use Lockers
Receive webhooks from your Locker
Get notified when members, courses, events, or posts change, and handle retries and failures.
The short version
- An outbound webhook tells your own system when something changes in the community, so the system does not have to keep asking the API whether anything has changed.
- The endpoint signing secret is shown once, and your receiver uses it to confirm a delivery came from Lockers.
- Deliveries can repeat and can arrive out of order, so the receiver should ignore duplicates by event ID and read current detail from the API.
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
Lockers then shows the Endpoint signing secret once. Select Copy secret and put it wherever your receiving system reads its configuration, not in source control. It starts with whsec_, and it is not a second API key: it proves a delivery came from us and cannot call the API on its own. Store it with the same care you give the API key, because anyone holding it can produce deliveries your system will trust.
- 1
Enter the URL
Enter your Endpoint URL. The placeholder, https://hooks.example.com/lockers, shows the shape we expect.
- 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
Restrict courses if you need to
Fill the course restrictions field if this endpoint should only hear about certain courses. Blank means all courses, and the restriction narrows course, enrollment, and completion events only.
- 4
Pick the events
Tick what you want under Events to deliver.
- 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
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, which is what the note under the field means by: Endpoint permissions and courses cannot exceed its grants. Once an endpoint points at a connection, it inherits that connection's ceiling. If the invitation events you want are out of reach, the connection itself is missing the Invitations permission, and the fix is on the key rather than the endpoint.
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 wire 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
That last one is the design rather than an inconvenience. Deliveries carry identifiers and small state hints, never member contact data or post bodies, so a delivery that lands in 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 instead of trusting the body as the 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 land after one from a minute ago. Because the body is a pointer rather than the record, reading the current state from the API settles which version is real.
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 for good and asks: Delete this endpoint? Pending deliveries for it will no longer be sent. Anything queued for that endpoint goes with it, so pause is the better move if you expect to turn it back on.
When a delivery fails
Failures land in Failed operations. Each row offers Replay failed row, which asks: Replay this exact failed row? Delivered or processed work cannot be replayed. Replay covers the delivery that never got through, not work Lockers already completed. It needs an active Pro plan, and on a Locker without one the message reads: An active Pro plan is required to replay delivery.
Treat that list as a repair tool and not as your record of what happened. We make no promise about how long a failed row stays there, so the receiving system should keep its own log of the events it has processed.
Build the smallest useful version of your community.
Start with a feed, classroom, calendar, messages, and member list. No card required.
Start a community