Webhooks Guide

Webhooks let you receive real-time notifications when events occur in your Steward account. Instead of polling the API, Steward sends HTTP POST requests to your configured URL.

Environment: Examples use Production (https://api.getsteward.ai) with an stw_live_… key. For Sandbox, use https://api.steward-sandbox.com with an stw_test_… key.

Creating a Webhook

curl -X POST https://api.getsteward.ai/api/v1/webhooks \
  -H "Authorization: Bearer stw_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/steward",
    "events": ["application.submitted", "application.approved"]
  }'

The response includes a signing secret - store it securely. It is only returned once.

{
  "id": "wh_507f1f77bcf86cd799439011",
  "url": "https://your-app.com/webhooks/steward",
  "events": ["application.submitted", "application.approved"],
  "secret": "whsec_abc123...",
  "status": "ACTIVE"
}

Available Events

Event	Description
application.created	A new application was created
application.onboarding_started	Applicant began the onboarding flow
application.submitted	Application was submitted for review
application.updated	An application’s details were updated
application.approved	Application was approved
application.rejected	Application was rejected
screening.created	Compliance screening was initiated
screening.updated	Screening results were updated
screening.hit_updated	A screening hit status was changed
document.uploaded	A document was uploaded
risk_score.created	Risk score was calculated
risk_score.updated	Risk score was recalculated
reviewer.assigned	A reviewer was assigned to an application
reviewer.unassigned	A reviewer was removed from an application
note.created	A note was added
note.updated	A note was modified
note.deleted	A note was deleted

Payload Format

Each webhook delivery includes:

{
  "event": "application.submitted",
  "timestamp": "2026-03-30T15:00:00.000Z",
  "data": {
    "entityType": "APPLICATION",
    "entityId": "507f1f77bcf86cd799439011",
    "accountId": "acc_123"
  }
}

Headers:

Header	Description
X-Webhook-Signature	HMAC-SHA256 signature of the request body
X-Webhook-Event	Event type (e.g., application.submitted)
X-Webhook-Delivery-ID	Unique delivery ID for idempotency (stable on retries)
Content-Type	application/json

Verifying Signatures

Verify the X-Webhook-Signature header to ensure the request came from Steward:

import { createHmac } from 'crypto'

function verifyWebhookSignature(body, signature, secret) {
  const expected = createHmac('sha256', secret).update(body).digest('hex')

  return signature === expected
}

Warning: Always verify webhook signatures before processing payloads. Without verification, an attacker could send fake events to your endpoint.

Idempotency

Each delivery includes an X-Webhook-Delivery-ID header that is unique per delivery and remains the same across retries. Use this ID to deduplicate events and ensure your handler processes each event only once.

const deliveryId = request.headers['x-webhook-delivery-id']
const alreadyProcessed = await cache.get(`webhook:${deliveryId}`)

if (alreadyProcessed) {
  return res.status(200).send('OK')
}

// Process the event...

await cache.set(`webhook:${deliveryId}`, true, { ttl: 300 })

Retry Policy

Failed deliveries are retried up to 5 times with exponential backoff:

Attempt	Delay
1	30 seconds
2	2 minutes
3	10 minutes
4	1 hour
5	4 hours

After all retries are exhausted, the delivery is marked as failed. Use the deliveries endpoint to check delivery status.

Managing Webhooks

Update or delete webhooks via the API:

# Update events
curl -X PATCH https://api.getsteward.ai/api/v1/webhooks/{id} \
  -H "Authorization: Bearer stw_live_..." \
  -d '{"events": ["application.submitted"]}'

# Pause
curl -X PATCH https://api.getsteward.ai/api/v1/webhooks/{id} \
  -H "Authorization: Bearer stw_live_..." \
  -d '{"status": "PAUSED"}'

# Delete
curl -X DELETE https://api.getsteward.ai/api/v1/webhooks/{id} \
  -H "Authorization: Bearer stw_live_..."