Webhook Management
Register endpoints to receive real-time event notifications from Rassmi.
Available Events
| Event | Trigger |
|---|---|
order.confirmed |
Agent confirms an order (status → confirmed) |
order.cancelled |
Agent cancels an order (status → canceled) |
inventory.updated |
Stock quantity updated via the inventory API |
/api/v1/webhooks
Register Webhook
Request Body
{
"url": "https://mystore.com/hooks/rassmi",
"events": ["order.confirmed", "order.cancelled"]
}
curl -X POST 'https://rassmi.com/api/v1/webhooks' \
-H 'Authorization: Bearer rsk_your_key' \
-H 'Content-Type: application/json' \
-d '{"url":"https://mystore.com/hooks/rassmi","events":["order.confirmed"]}'
Response 201
{
"data": {
"id": "019ea6a5-0b2f-71f8-8b74-958aae166f5e",
"url": "https://mystore.com/hooks/rassmi",
"events": ["order.confirmed", "order.cancelled"],
"is_active": true,
"signing_secret_hint": "whsec_a1b2..."
},
"signing_secret": "a1b2c3d4e5f6..."
}
signing_secret is returned only once at creation.
Store it securely.
/api/v1/webhooks
List Webhooks
curl 'https://rassmi.com/api/v1/webhooks' \
-H 'Authorization: Bearer rsk_your_key'
/api/v1/webhooks/{id}
Delete Webhook
curl -X DELETE 'https://rassmi.com/api/v1/webhooks/019ea6a5-0b2f-71f8-8b74-958aae166f5e' \
-H 'Authorization: Bearer rsk_your_key'
Webhook Security
Verify that webhook events are genuinely sent by Rassmi.
Signature Verification
Every webhook POST includes an X-Rassmi-Signature header containing an HMAC-SHA256
hash of the raw request body, signed with your webhook's signing secret.
POST /hooks/rassmi HTTP/1.1
Content-Type: application/json
X-Rassmi-Event: order.confirmed
X-Rassmi-Signature: sha256=a1b2c3d4e5f6...
X-Rassmi-Delivery: unique-request-id-12345
Payload Structure
Below are example payload structures for each supported event:
{
"event": "order.confirmed",
"timestamp": "2026-08-04T22:47:15+00:00",
"data": {
"id": "6de37dd8-2951-4149-8e0c-d10b8f6d1743",
"status": "confirmed",
"customer_name": "Youcef Benali",
"customer_phone": "0777989898",
"total_amount": 2500,
"updated_at": "2026-08-04T22:46:58+00:00"
}
}
{
"event": "order.cancelled",
"timestamp": "2026-08-04T22:53:02+00:00",
"data": {
"id": "6de37dd8-2951-4149-8e0c-d10b8f6d1743",
"status": "canceled",
"customer_name": "Youcef Benali",
"customer_phone": "0777989898",
"total_amount": 2500,
"updated_at": "2026-08-04T22:52:51+00:00"
}
}
{
"event": "inventory.updated",
"timestamp": "2026-08-04T22:59:04+00:00",
"data": {
"product_id": "019ea6a5-0b2f-71f8-8b74-958aae166f5e",
"sku": "BRM-001",
"old_quantity": 69,
"new_quantity": 68
}
}
Verifying the Signature
Compute HMAC-SHA256 over the raw request body string using your signing secret,
then compare it to the sha256=... value in the header.
# Signature verification is done server-side.
hash_equals in PHP,
crypto.timingSafeEqual in Node.js) to prevent timing attacks.
Retry Policy
If your endpoint returns a non-2xx response or times out, Rassmi will retry
automatically:
Your endpoint must respond within 3 seconds. Return any
2xx status code to acknowledge receipt.