Webhooks API

Webhook management requires a portal bearer token, membership in the target organization, and Starter or higher. Delivery targets must use public HTTPS URLs; private, loopback, link-local, and internal hostnames are rejected.

Supported events

• email.check.completed
• email.check.failed
• order.fraud.detected
• order.fraud.alert
• profile.risk.changed
• cashier.fraud.detected
• mdm.device.enrolled
• mdm.device.compliance_changed
• mdm.command.completed

Create

curl -X POST https://api.simplr-ai.com/v1/webhooks \
  -H "Authorization: Bearer $SIMPLR_PORTAL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "org_id": "YOUR_ORG_ID",
    "url": "https://yourapp.com/webhooks/simplr",
    "events": ["email.check.completed", "order.fraud.alert"],
    "description": "Production risk events"
  }'

The response returns the signing secret once. Store it immediately; later reads expose only secret_prefix.

Manage and inspect delivery

Method	Path	Purpose
GET	/v1/webhooks?org_id=:orgId	List endpoints
GET	/v1/webhooks/:id?org_id=:orgId	Get one endpoint
PATCH	/v1/webhooks/:id	Change URL, events, description, or status
DELETE	/v1/webhooks/:id?org_id=:orgId	Delete an endpoint
POST	/v1/webhooks/:id/roll-secret	Rotate and return a new signing secret once
GET	/v1/webhooks/:id/deliveries?org_id=:orgId	Inspect recent attempts
POST	/v1/webhooks/:id/test	Queue a test email.check.completed event
POST	/v1/webhooks/deliveries/:deliveryId/retry	Retry a failed or exhausted delivery

Mutating requests include org_id in their JSON body. Read/delete requests use the query parameter. Pause or resume an endpoint by setting its status to paused or active with PATCH.

Delivery and signature

Each delivery is JSON and includes an event id, event type, ISO timestamp, and event-specific data. Simplr sends:

• X-Simplr-Signature: t=<unix-seconds>,v1=<hex-hmac>
• X-Simplr-Event: <event-type>
• X-Simplr-Delivery: <event-id>

Compute HMAC-SHA256 over <timestamp>.<raw-request-body> using the stored webhook secret and compare it with v1 using a timing-safe comparison. Reject stale timestamps according to your replay window and deduplicate using X-Simplr-Delivery.

Failed deliveries are retried and remain visible in delivery history. Return a 2xx response quickly and process work asynchronously.