# Error Handling & Retries

Webhooks, by nature, depend on reliable delivery. UseStencil handles failures gracefully and provides an automatic retry mechanism to help ensure webhook events are not lost due to temporary issues on the receiving server.

This section explains:

* What counts as a delivery failure
* How and when retries are triggered
* Best practices for ensuring reliability

## What Is Considered a Failure?

UseStencil considers a webhook delivery failed if:

* The server responds with a non-2xx HTTP status code (e.g., 400, 500, 403)
* The server times out (takes longer than 5 seconds to respond)
* The server drops the connection (e.g., TLS handshake failure, DNS error)

## Retry Behavior

If a webhook delivery fails, UseStencil will automatically retry the request using the following backoff strategy:

<table><thead><tr><th width="116.953125">Retry #</th><th>Delay (approx.)</th></tr></thead><tbody><tr><td>1</td><td>1 seconds</td></tr><tr><td>2</td><td>~4 seconds</td></tr><tr><td>3</td><td>~9 seconds</td></tr><tr><td>10</td><td>~1.7 minutes</td></tr><tr><td>20</td><td>~6.7 minutes</td></tr></tbody></table>

## Logging

Webhook integrations can fail due to temporary server issues, invalid URLs, or network hiccups. UseStencil ensures delivery robustness with a retry strategy and full visibility into delivery logs via your Webhook dashboard.

Every webhook configured in UseStencil includes a Delivery Log Viewer, which shows:

* A timestamped list of deliveries
* Thumbnail preview of the rendered image
* Success status (green tick for success, red icon for failures)
* A “View Details” option for payload and response inspection

Access the list of previous deliveries via this screen.

<figure><img src="/files/etgBm6Fosuzoxqrl7hGU" alt=""><figcaption></figcaption></figure>

**Example delivery log**

<figure><img src="/files/AQ6vg0IV016V8FO2LkHR" alt=""><figcaption></figcaption></figure>

1. Go to your Webhook configuration page
2. Click the ⋮ menu next to your webhook URL
3. Select "View deliveries"
4. You'll see a list of all past attempts, with:
   * Event preview (e.g., generated image)
   * Exact date and time
   * Status icon
   * "View Details" button

## Test Webhook Feature

To quickly validate your endpoint without triggering a real event, use the Send Test Webhook button on the delivery log screen.

UseStencil will immediately fire a test payload to your configured URL, following the same structure and headers as a real webhook.

This is useful for:

* Verifying endpoint availability
* Testing authentication
* Debugging custom handling logic

## Best Practices

| ✅ Respond with 200 OK immediately                      | Avoids timeout and duplicate retries                   |
| ------------------------------------------------------ | ------------------------------------------------------ |
| ✅ Make handler idempotent                              | Retries may cause duplicates                           |
| ✅ Use the user\_defined field for traceability         | Helps identify environments, orgs, or source triggers  |
| ✅ Log incoming requests                                | Enables postmortem debugging                           |
| ✅ Use the “Send Test Webhook” feature before deploying | Ensure payload + auth + headers are handled correctly. |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.usestencil.com/integrations/webhook-integration/error-handling-and-retries.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.