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:

Retry #	Delay (approx.)
1	1 seconds
2	~4 seconds
3	~9 seconds
10	~1.7 minutes
20	~6.7 minutes

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.

Example delivery log

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.