Webhooks

{
  "source": "web",
  "store": null,
  "status": "trialing",
  "tier": "pro",
  "effectiveAt": "2026-09-08T09:14:03.000Z"
}

status is trialing or active.

{
  "source": "mobile",
  "store": "app_store",
  "tier": "pro",
  "periodStartsAt": "2026-09-08T09:14:03.000Z",
  "periodEndsAt": "2026-10-08T09:14:03.000Z",
  "isTrialConversion": false
}

isTrialConversion and isResubscription are included when they apply.

{
  "source": "mobile",
  "store": "app_store",
  "tier": "pro",
  "reason": "user_request",
  "accessEndsAt": "2026-10-08T09:14:03.000Z"
}

reason is one of user_request, payment_failed, billing_error or unknown.

{
  "source": "mobile",
  "store": "app_store",
  "tier": "pro",
  "reason": "billing_error"
}

reason is one of user_request, payment_failed, billing_error or unknown.

{
  "source": "web",
  "store": null,
  "tier": "pro",
  "reason": "payment_failed",
  "attempt": 2,
  "nextRetryAt": "2026-09-10T09:14:03.000Z"
}

attempt and nextRetryAt can be null when the payment provider does not report them.

{
  "source": "web"
}

source is web or mobile.

{
  "source": "web"
}

source is web or mobile.

{
  "source": "web",
  "category": "negative"
}

category is one of positive, negative, report, harmful, untrue or unhelpful.

{
  "used": 50,
  "limit": 50,
  "unit": "messages",
  "window": "rolling-24h",
  "resetsAt": "2026-09-09T09:14:03.000Z"
}

A user who keeps sending after reaching the limit can trigger more than one of these events.

{
  "used": 3600,
  "limit": 3600,
  "unit": "seconds",
  "window": "rolling-24h",
  "resetsAt": "2026-09-09T09:14:03.000Z"
}

A user who keeps calling after reaching the limit can trigger more than one of these events.

{}

data is empty. Use it to check that your endpoint is reachable.

• Respond with any 2xx status code to confirm you received the event.
• Respond within 15 seconds. A slower response counts as a failure.
• Save the event and respond first, then do any slow work afterwards.
• Any other response, including a redirect, counts as a failure and is retried.

Every webhook is signed with your endpoint’s signing secret, so you can confirm it came from Steno and was not changed.

Each request carries a message ID, a timestamp and a signature in its headers. The signature is an HMAC-SHA256 of the message ID, the timestamp and the raw request body, using your signing secret. Retries of the same event reuse the same message ID. Your developer should:

1. Verify the signature against the raw, unparsed request body before using the event.
2. Reject requests whose timestamp is more than 5 minutes old or in the future.
3. Reject any request that fails either check with a non-2xx status.

We share the exact header names and sample verification code for your language during onboarding.

Open the endpoint, go to Settings, and click Rotate next to the signing secret. You can keep the old secret working for 24 hours (recommended) or 7 days while you deploy the new one, or stop it immediately. During that time, requests are signed with both secrets.

If your endpoint does not respond with a 2xx in time, we retry the event. After the first attempt, we retry after 5 seconds, 5 minutes, 30 minutes, 2 hours, 5 hours, 10 hours and 10 hours again. After the last retry, the event is marked as failed.

If every delivery to an endpoint keeps failing for 5 days, the endpoint is turned off. Turn it back on with the live switch on its Settings tab.

An event can arrive more than once, for example when your endpoint times out after processing it. The id stays the same across deliveries, so store the IDs you have processed and skip repeats.

Events can arrive in a different order from the order they happened. If order matters, use occurredAt instead of arrival order.

If your endpoint was down, open the endpoint and use Send missed events again. Choose how far back to go (the last hour, the last 24 hours, or a time you pick), and whether to resend only failed events or everything in that window.

To resend a single event, open it from the Deliveries tab and click Resend.

• Send a test event. Open the endpoint and click Send test event on the Overview tab. You can send an example of any event type. Test events have isTest: true.
• Check deliveries. The Deliveries tab lists every delivery with its result. Open one to see the request we sent, your endpoint’s response, and each attempt.