Aglet

Triage a webhook non-2xx response

A non-2xx status can mean an invalid event, temporary dependency, duplicate, or handler failure. Freeze one response and record event identity, status, response time, receipt, side effect, and retry. Keep sender interpretation separate from the receiver’s intended disposition in one handler path.

Establish what is happening

  1. Capture the response decision

    Record endpoint, event and delivery IDs, status, response time, handler branch, receipt, and effect state. Redact payload and secret. Note whether the response happened before or after durable receipt. Keep the event identity with the status.

  2. Compare neighboring statuses

    Run safe fixtures for validation, duplicate, transient dependency, authorization, and success. Compare status, body detail, sender retry expectation, and local state. A generic 500 can hide a deliberate discard or an unfinished write.

  3. Bound retry outcomes

    Group responses by status, event type, endpoint, handler revision, attempt, and effect. Separate repeated invalid events from recoverable failures and successful duplicates. Mark unknown sender behavior rather than assuming every non-2xx retries.

What to carry forward

Triage ends with one status, intended disposition, receipt and effect state, retry evidence, and affected cohort. Stop changing statuses ad hoc. Route response policy, handler, and sender questions separately. Keep unknown sender behavior explicit in the record.

Technical background: Zendesk developer documentation.

Keep the decision with the work.

Use a Work Item in Aglet to record the problem, the evidence you have, and the next decision. Add an owner and priority, then keep updates in the discussion so the next person can follow the reasoning.

Create an account See the product workflow