Skip to main content
Webhooks are HTTP callbacks that send real-time POST requests to your configured endpoints when specific events occur in Stora. When an event happens — such as an invoice being paid or a unit becoming occupied — Stora immediately notifies all endpoints subscribed to that event type.

Getting started

1

Create a webhook endpoint

Use the Developer Portal to manage webhook endpoints for a test operator or connected operator account. You can also use the Webhook Endpoints API to register a publicly accessible HTTPS URL, the event types you want to subscribe to, and the API version.
2

Store your secret key

When you create an endpoint, Stora generates a secret key. Store it securely — you’ll use it to verify incoming requests.
3

Handle incoming events

Build a handler at your URL that verifies the signature, processes the event, and returns a 2xx response.

Payload structure

Every webhook delivers a JSON payload with this structure:

Headers

Every webhook request includes these headers:

Signature verification

All webhook requests are signed using HMAC SHA256. Always verify the signature before processing. The signature is in the X-Stora-Signature header:
To verify:
  1. Extract the timestamp (t) and signature (v1) from the header
  2. Reconstruct the signed payload: {timestamp}.{raw_request_body}
  3. Compute the HMAC SHA256 using your endpoint’s secret key
  4. Compare the computed signature with v1
  5. Optionally, check the timestamp is recent to prevent replay attacks

Retries

Stora automatically retries failed deliveries up to 6 times: A delivery is retried when your endpoint returns a non-2xx status code, a network error occurs, or the request times out (20-second limit). After 6 failed attempts, the delivery is marked as failed. If the endpoint is deleted or disabled before a scheduled retry, pending retries are cancelled.

Best practices

Return a 2xx response as quickly as possible — even if you process the event asynchronously. This prevents unnecessary retries.
  • Implement idempotency — use event.id to ensure you don’t process the same event twice. Store processed event IDs and check before processing.
  • Process asynchronously — for time-consuming operations, queue the webhook for background processing after returning a success response.
  • Log the request ID — use X-Stora-Request-Id to correlate retry attempts when debugging.
  • Validate signatures — always verify the HMAC signature before processing.
  • Monitor your endpoint — extended downtime may exhaust all retry attempts.

Available events

For full payload schemas, see the Webhooks section in the API reference.