Skip to main content

​
What are Zenstep webhooks?

Webhooks allow Zenstep to push event notifications to your server in real time. Instead of polling the API, you register a URL and Zenstep sends an HTTP POST request to it whenever a relevant event occurs.

​
Supported events

Webhook alerts (step.broken, step.recovered) require the Grow plan or higher.

​
Setting up a webhook

  1. Go to Settings → Notifications in the dashboard.
  2. Click Add webhook endpoint.
  3. Enter your endpoint URL (must be HTTPS).
  4. Select which events to subscribe to.
  5. Click Save.
Zenstep will immediately send a test ping to your endpoint to verify it’s reachable.

​
Delivery guarantees

  • Webhooks are delivered at least once — your endpoint may receive the same event multiple times in rare failure scenarios. Make your handler idempotent.
  • Zenstep retries failed deliveries with exponential backoff for up to 72 hours.
  • A delivery is considered successful if your endpoint returns a 2xx status code within 10 seconds.

​
Retry schedule

After 10 failed attempts (approximately 72 hours), the delivery is abandoned.

​
Responding to webhooks

Your endpoint must return a 2xx status code within 10 seconds. If you need to do long-running processing, acknowledge the webhook immediately and process asynchronously:

​
Testing webhooks

Use ngrok or Hookdeck to expose a local server during development:
Or use the Test button next to each webhook endpoint in the dashboard — it sends a sample payload.