Testing webhooks
The quickest real event
A send on a test key records the message and fires a real
delivery.delivered webhook, without mail leaving the platform and without
touching your allowance:
curl -X POST https://api.lockally.com/v1/send \
-H "Authorization: Bearer lk_test_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: webhook-test-1" \
-d '{"from":"test@yourdomain.com","to":["someone@example.com"],
"subject":"webhook test","text":"hello"}'
The event carries "test": true in its data, so your handler can tell it
apart if it needs to. See Live and test keys.
Forcing an outcome
A delivered event only proves the happy path. To exercise bounce and complaint handling:
POST /v1/sandbox/messages/{id}/simulate
Use the id from the test send. This raises the delivery event you ask for,
with the same envelope and signature a real one would have, which is the only
practical way to test bounce handling without harming a real address.
Receiving it locally
Your endpoint has to be reachable from the internet, so during development
use a tunnel (ngrok, cloudflared or similar) and register the tunnel URL
as the webhook.
Register it as a separate webhook rather than repointing your production one. Then you can delete it afterwards without touching anything real, and a forgotten tunnel URL cannot silently become your production endpoint.
What to check, in order
The signature verifies. Over the raw body, before any parsing. This is the single most common mistake, because a framework that parses and re-serialises JSON changes the bytes and every signature then fails. See Signature verification.
A tampered body is rejected. Change one character in the payload, keep the signature, and confirm your handler refuses it. A verifier that never rejects anything is not a verifier, and nothing else you test will reveal that.
An old timestamp is rejected. Replay a request from more than five minutes ago and confirm it fails.
A duplicate is ignored. Send the same event twice and confirm your handler acts once. You will get duplicates in production.
You answer within 10 seconds. Anything slower is treated as a failure and retried, however correct the work was.
You return 2xx for events you do not handle. A non-2xx on an event you simply ignore spends retries and moves the endpoint toward being paused.
Testing the failure path
Return a 500 deliberately and watch the retries arrive: 30 seconds, then a
minute, then two. It is worth seeing once, because it makes
the retry schedule concrete and confirms
your handler is idempotent under genuine repetition rather than a test
harness.
Return 2xx again and the streak resets.
Verifying without a webhook at all
GET /v1/events returns the same envelopes on demand.
It will not test your signature verification, since you are reading rather
than receiving, but it is the fastest way to see what an event’s data
actually contains before you write code against it.