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
POST /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..."
}
The signing_secret is returned only once at creation. Store it securely.
GET /api/v1/webhooks List Webhooks
curl 'https://rassmi.com/api/v1/webhooks' \
  -H 'Authorization: Bearer rsk_your_key'
DELETE /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.

Webhook Headers
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:

order.confirmed
{
  "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"
  }
}
order.cancelled
{
  "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"
  }
}
inventory.updated
{
  "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.
Always use timing-safe comparison (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:

Attempt 1 Immediate dispatch
Attempt 2 +10 minutes
Attempt 3 +2 hours
Final Attempt +12 hours

Your endpoint must respond within 3 seconds. Return any 2xx status code to acknowledge receipt.