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.

      Reliability

      Your endpoint will be unavailable at some point. This page is the numbers you need to design for that: how long you have to recover, what you lose if you do not, and what arrives twice or late when you do.

      Retries

      Attempts per delivery 12, including the first
      Backoff exponential, capped at 6 hours
      Request timeout 10 seconds
      Email alert after 5 consecutive failures on an endpoint
      Auto-pause after 50 consecutive failures on an endpoint

      A delivery is retried when your endpoint returns a non-2xx status, when the connection fails, or when it does not answer within 10 seconds.

      Answer fast and do the work later. The timeout is on your whole response, so an endpoint that processes synchronously can fail on load alone. Return 2xx as soon as you have stored the event, and process it afterwards.

      Duplicates

      Delivery is at-least-once. You will receive the same event more than once, and not only when something is wrong: a response we never saw is retried even though your endpoint handled it.

      Deduplicate on the envelope’s id, which is stable across every retry of the same event:

      if store.seen(event["id"]):
          return 200
      store.record(event["id"])
      process(event)

      Record the id before you act, in the same transaction where possible. The failure this avoids is processing an event, crashing before recording it, and processing it again on the retry.

      Do not deduplicate on created, on a message id, or on the payload: several distinct events can share all three.

      Ordering

      So delivery.delivered can arrive before the delivery.deferred that preceded it, and a bounce can arrive after you believed the message settled.

      Design for it rather than hoping. Two approaches, and the second is usually right:

      Use created, the envelope’s Unix seconds, to discard an update older than the state you hold. Cheap, and sufficient when you only track a latest status.

      Treat each event as a fact rather than a transition. Record that a bounce happened, rather than moving a state machine from “delivered” to “bounced”. Facts commute; transitions do not.

      When your endpoint fails

      Five consecutive failures sends an email to the account’s alert address, once per streak rather than per failure.

      Fifty consecutive failures pauses the subscription. A paused webhook receives nothing, and the pause is visible on the dashboard. Resume it by updating the webhook; new events flow again from that moment.

      Events raised while paused are not queued for you. They are in the event log for 7 days, which is the only way back.

      A streak is consecutive: one success resets it, so an endpoint that is flapping can stay unpaused indefinitely while losing individual events to the 12-attempt limit. Watch for the alert mail rather than relying on the pause to tell you something is wrong.

      What to return

      2xx Accepted. Nothing is retried
      anything else Retried, up to the limit
      no response in 10s Retried

      Return 2xx even for an event you do not care about or cannot parse. A non-2xx means “try again”, and retrying will not make an unrecognised event recognisable; it just spends your 12 attempts and moves you toward a pause.