Webhook Delivery & Troubleshooting
NextStep automatically retries failed deliveries and provides detailed logs to help you debug issues.
Delivery Process
When an event occurs, NextStep sends an HTTP POST request to your webhook URL with a 10-second timeout. If the request succeeds (2xx response), the delivery is marked as complete.
Retry Schedule
If a delivery fails (non-2xx response or timeout), NextStep retries with exponential backoff:
| Attempt | Timing |
|---|---|
| 1st attempt | Immediate |
| 2nd attempt | After 5 minutes |
| 3rd attempt | After 30 minutes |
| 4th attempt | After 2 hours |
Each webhook gets up to 3 retry attempts (4 total including the initial delivery).
Auto-Disable
If a webhook fails 10 consecutive times across any deliveries, it is automatically disabled to prevent further failed requests. You’ll see a warning banner on the webhook indicating the failure count.
To re-enable a disabled webhook:
- Fix the issue with your endpoint.
- Go to Settings > Webhooks.
- Toggle the webhook back on.
Re-enabling resets the failure counter.
Delivery Logs
View the last 50 deliveries for your team in the Webhooks settings:
- Go to Settings > Webhooks.
- Scroll down to the Delivery Logs section.
- Click on a delivery to expand its details.
Each log entry shows:
- Status —
delivered,failed,pending, ordelivering - Event type — Which event triggered the delivery
- Attempts — How many attempts have been made (e.g., 2/4)
- Response status — The HTTP status code returned by your endpoint
- Error message — If the delivery failed, the error details
- Response body — The first 500 characters of your endpoint’s response
- Payload — The full JSON payload that was sent
Delivery logs are automatically cleaned up after 30 days.
Common Issues
Endpoint Returns Non-2xx Status
Make sure your endpoint returns a 200 (or any 2xx) status code on success. Any other status code is treated as a failure and will trigger retries.
Timeout Errors
Webhook requests have a 10-second timeout. If your endpoint takes longer than this to respond, the delivery will fail. To fix this:
- Process the webhook data asynchronously (return 200 immediately, then process in the background).
- Optimise your endpoint’s response time.
HTTPS Required
Webhook URLs must use HTTPS. HTTP endpoints are not supported.
Webhook Not Firing
If a webhook isn’t firing for process_step.completed events, make sure you’ve enabled “Send webhook on completion” on the specific task in the process editor. This event type requires per-task opt-in.
For process_run.created and process_run.completed events, check that:
- The webhook is enabled (not toggled off or auto-disabled).
- The correct events are selected on the webhook.