Testing webhooks locally
Your handler runs on localhost. Our dispatcher is on the public internet and
will not reach it. Everything below is about closing that gap without
weakening the thing you are trying to test.
Testing webhooks covers how to cause an event. This page is about where it lands.
Use a tunnel, not a mock
A tunnel gives your laptop a public HTTPS URL that forwards to a local port. ngrok, Cloudflare Tunnel and similar tools all do this.
-
Start your handler on whatever port it uses.
-
Open a tunnel to that port and copy the HTTPS URL it prints.
-
Register it as a webhook endpoint, subscribing only to the events you are working on.
curl -sS -X POST https://api.lockally.com/v1/webhooks \ -H "Authorization: Bearer $LOCKALLY_TEST_KEY" \ -H "Content-Type: application/json" \ -d '{"url":"https://your-tunnel.example/hooks/lockally", "events":["delivery.delivered","delivery.bounced"]}' -
Cause an event with a test-key send, then force an outcome if you want a failure.
-
Delete the endpoint when you are done, or it keeps failing against a tunnel URL that no longer resolves.
The reason to prefer this over replaying a captured payload into your handler
by hand: the signature. A tunnelled event arrives with a real t=,v1= header
over a real TLS connection, so your verification runs for real. A replayed
fixture almost always has verification switched off or stubbed, which means the
one security-critical part of the handler is the part you never test.
Clean up, and why it matters here
A dead tunnel URL keeps failing. The dispatcher retries 12 times with backoff capped at 6 hours, alerts at 5 consecutive failures, and pauses the endpoint after 50. A forgotten laptop endpoint will therefore generate alerts and can pause itself, which is confusing a week later when you have forgotten it exists.
Delete the endpoint, or at minimum unsubscribe it, when you close the tunnel.
If you cannot use a tunnel
Some networks forbid them. Two workable alternatives, both with a stated cost:
Deploy the handler to a staging host and point the endpoint there. You lose the debugger; you keep the real signature and the real transport. Combine it with the event log to see what we sent and what we got back.
Capture and replay. Record a real event once from a staging endpoint, then replay it locally. You keep the debugger and lose signature verification, since the timestamp in a stored signature will fall outside the tolerance window. Treat that as a test of your business logic only, and never let the replay path exist in production code.
Reading what we think happened
Whatever route you take, the authoritative record of a delivery attempt is on our side, not in your logs:
curl -sS "https://api.lockally.com/v1/events?type=delivery.bounced" \
-H "Authorization: Bearer $LOCKALLY_TEST_KEY"
Scope webhooks:read. The event log requires Starter or above, so on Free
this is not available and your own logging is all you have.