Lockally

      Use your API key in the examples

      Replaces lk_live_… in the code samples on this site so you can copy and run them. It is stored in this browser only and is never sent anywhere, including to Ask AI.

      It will be visible on the page. Use a test key if you are sharing your screen or taking screenshots.

      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.