Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.getzenstep.com/llms.txt

Use this file to discover all available pages before exploring further.

​
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

EventTrigger
step.brokenA step’s DOM element cannot be found (health = broken)
step.recoveredA previously broken step is found again
flow.completedA user completes a flow
flow.dismissedA user dismisses a flow
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

AttemptDelay
1Immediate
25 minutes
330 minutes
42 hours
58 hours
624 hours
7–1024 hours
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: 
// Express.js example
app.post("/webhooks/zenstep", express.json(), (req, res) => {
  // Acknowledge immediately
  res.sendStatus(200);

  // Process asynchronously
  processWebhook(req.body).catch(console.error);
});

​
Testing webhooks

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