Webhooks

Webhooks let AuraBoot notify external systems when business events occur. They are commonly used to connect AuraBoot with CRMs, ERPs, support tools, workflow systems, data pipelines, and custom internal services.

Event flow

Command executes
  -> domain event is created
  -> event is stored for reliable delivery
  -> webhook dispatcher matches subscriptions
  -> HTTP POST is sent to target URL
  -> delivery result is logged

The runtime should treat webhook delivery as at-least-once. Receivers should be idempotent.

Subscription model

A webhook subscription typically includes:

An eventType is the string a subscription listens for. When a command-completion rule does not set an explicit event type, it falls back to the command code (for example qualify_crm_lead), so subscriptions commonly listen on a command code.

Example subscription

{
  "name": "Qualified Lead Webhook",
  "targetUrl": "https://example.com/webhooks/aura",
  "eventType": "qualify_crm_lead",
  "modelCode": "crm_lead",
  "filterExpression": "status == 'qualified'",
  "secret": "replace-with-strong-secret",
  "maxRetries": 3,
  "timeoutMs": 10000,
  "enabled": true
}

Payload shape

The command pipeline builds the payload from the command code, model code, the command input fields, and the command result, so the receiver can identify the operation and read the data:

{
  "commandCode": "qualify_crm_lead",
  "modelCode": "crm_lead",
  "payload": {
    "status": "qualified"
  },
  "result": {
    "status": "qualified"
  }
}

payload is the command input; result is the field mapping and handler result after execution.

Signature verification

When a subscription has a secret, the webhook request is signed with HMAC-SHA256. The receiver recomputes the signature using the shared secret and rejects mismatches.

X-Webhook-Event: qualify_crm_lead
X-Webhook-Timestamp: 1747214400000
X-Webhook-Signature: sha256=<hex-digest>

X-Webhook-Event is the event the subscription listens for (the command code when no explicit event type is set), X-Webhook-Timestamp is the delivery time in epoch milliseconds, and X-Webhook-Signature is present only when a secret is configured.

Retry behavior

External systems fail. AuraBoot should retry failed deliveries with backoff. Receivers should avoid side effects that cannot tolerate duplicate delivery.

Security guidelines

• Use HTTPS target URLs.
• Verify HMAC signatures.
• Reject old timestamps if replay protection is enabled.
• Keep webhook secrets out of logs.
• Make receiver handlers idempotent.
• Use narrow event filters instead of sending every event.

Testing

Use a test endpoint first:

curl -X POST http://localhost:6443/api/webhooks/<pid>/test \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sample": true}'

Then verify the delivery log before binding production workflows.

Next steps

• Command Pipeline
• Commands
• REST API