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 theX-Stora-Signature header:
- Extract the timestamp (
t) and signature (v1) from the header - Reconstruct the signed payload:
{timestamp}.{raw_request_body} - Compute the HMAC SHA256 using your endpoint’s secret key
- Compare the computed signature with
v1 - 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
- Implement idempotency — use
event.idto 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-Idto 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
Contact
Contact
Contract
Contract
Coupon
Coupon
Credit Note
Credit Note
Deal
Deal
Identity Verification
Identity Verification
Invoice
Invoice
Note
Note
Order
Order
Protection Level
Protection Level
Subscription
Subscription
Task
Task
Tenancy
Tenancy
Unit
Unit
Unit Type
Unit Type