Explaining Cursor Pagination Tokens to API Consumers
When a client requests a large collection from an API, the server often sends the results in parts. A cursor pagination token…
Categories
Explaining Webhook Failures to Non-Technical Teams
When one service needs to tell another that something happened, such as an order being placed, it sends an automated message called a webhook. The sending service is the sender, and the receiving service is the receiver. The sender reports a webhook failure when it does not record the delivery as successful under its rules. That report alone does not show whether the event was lost or which service caused the problem.
When explaining an incident, identify which of three outcomes occurred: the sender made no delivery attempt, an attempt failed, or the receiver acknowledged the message but has not confirmed that it completed the requested business action. This distinction helps product, support, and operations staff describe what happened and collect useful evidence before escalating.
Identify where delivery stopped
A webhook passes through several stages: the sender checks whether an event matches the subscription, tries to contact the receiver, and receives a response. The receiver then handles the message. A subscription is the configuration that tells the sender which events to send and where to send them. The sender’s delivery history shows whether it attempted delivery. Receiver logs show whether the request arrived and what happened next. GitHub’s troubleshooting guidance also separates events with no recorded attempt from attempted deliveries that failed.
| Failure category | What to tell colleagues | Evidence to check |
|---|---|---|
| No event or attempt found | The sender has no recorded attempt for the event. The event may not match the subscription, the subscription may be inactive, or the sender may not have logged the attempt yet. | Confirm the event type, the affected account or record, subscription status, and sender delivery history. |
| Connection failure | The sender could not reach the receiver’s address. A hostname lookup, network rule, or unavailable endpoint may have stopped the connection. | Record the sender’s exact error, the destination address, the attempt time, and any relevant network changes. |
| Security certificate failure | The sender could not verify the receiver’s HTTPS certificate. HTTPS uses TLS, a protocol that protects a connection and helps verify the server’s identity. | Capture the exact certificate error and check certificate validity and whether the receiver provides the complete certificate chain. |
| Timeout or slow response | The receiver did not respond within the sender’s allowed time. A receiver that waits for lengthy work before replying can trigger this outcome. | Record the attempt duration and timeout message, then compare them with receiver latency and load at that time. |
| Unexpected response | The receiver replied, but the sender did not accept the response as successful. HTTP status codes describe the result: 2xx codes indicate success, 3xx indicate redirection, 4xx indicate a client error, and 5xx indicate a server error. The sender’s own rules determine which responses count as successful. |
Capture the exact status code, response text and headers, and any redirect destination. A status code narrows the investigation; it does not identify the cause on its own. |
| Authentication or signature rejection | The receiver could not verify that the message was genuine or that it matched the configured credentials. A signature is a cryptographic check based on a secret or key. | Record whether verification passed, the verification error, and whether credentials or request handling recently changed. Never include secret values in a ticket. |
| Payload or processing failure | The receiver got the message but could not interpret it or complete the intended work. For example, its code may reject the message’s format or a business rule may prevent an update. | Match the event or delivery ID to receiver logs, error details, queue status, and the affected business record. |
| Duplicate or out-of-order event | A repeated or delayed message may cause a second action or leave a record showing older information. | Compare event and delivery IDs, timestamps, retry history, and prior processing records before replaying the event. |
| Throttle or backlog | The sender or receiver is slowing delivery, or work is waiting in a queue. The business data may temporarily lag behind. | Check delivery times, retry counts, queue depth, and whether the delay affects one event type or many. |
These categories guide investigation without assigning fault. For example, a 4xx response points to a response from the receiver, but the status alone does not establish whether a configuration, request, or application rule caused it. HTTP status guidance describes the code classes; each webhook provider defines its own delivery rules.
Separate receipt from completed work
A sender’s successful delivery record confirms that it received an accepted response. It does not necessarily confirm that the receiver completed the business action. A receiver might acknowledge the message and process it later in a background queue. In HTTP, 202 Accepted specifically indicates that a request was accepted for processing, while the processing may not yet be complete or may not ultimately succeed. MDN’s explanation of 202 Accepted clarifies this distinction.
If someone says that “the webhook succeeded” but an order, account, or other record did not update, check both results: the sender’s delivery result and the receiver’s processing result. Check whether the receiver logged the request, placed it in a queue, and completed the intended update. Shopify’s troubleshooting guidance also directs operators to delivery details and receiver-side investigation.
Retry rules also depend on the provider. Some senders retry failed deliveries; others require an operator to request a redelivery. GitHub’s instructions for failed deliveries describe a provider-specific redelivery option. Check the relevant provider’s documentation before promising that a message will be retried or assuming that retrying is safe. A repeated delivery can trigger duplicate work unless the receiver checks whether it has already processed that event.
Collect evidence before escalation
When you escalate an incident, describe its impact and identify the last stage you confirmed. Collect these details, using identifiers and redacted information wherever possible:
- Business impact: What customer or operational outcome is missing, delayed, duplicated, or incorrect? How many records are affected, and is the issue still happening?
- Event details: Which provider and event type are involved? Include the event ID, delivery ID, and affected business record.
- Time details: Include the event and delivery-attempt times with time zones, and state the time range searched.
- Sender result: Say whether an attempt exists. Include its status, exact error or response code, duration, attempt number, and current delivery state.
- Destination and configuration: Identify the configured destination or a redacted host and path, the subscription, its active status, and any recent configuration changes.
- Receiver evidence: State whether the request appears in the proxy, load balancer, application, or queue logs. Include matching request IDs, response status, and processing errors.
- Security and recovery: Note whether signature verification passed and whether credentials or certificates recently changed. State whether anyone has retried or reconciled the event. Do not include secret values or unrestricted message contents.
Start by asking: Does the sender show an attempt? If it does not, check whether the event type matches the subscription, whether the subscription is active, and what the sender’s status shows. If an attempt appears, use the exact connection error, response, or timeout to guide the next investigation. If the sender records success but the business result is missing, trace the event through the receiver’s logs and processing records.
What I'm buildingDelegate tasks. Get software.
Give Vroni a GitHub issue, bug report, spec, or rough idea. It reads the repo, plans the change, writes code, runs checks, and works toward a review-ready pull request.
Take a look at vroni.com