Create webhook subscription

Subscribe to real-time events from Aura.

How it works:

1. Create a subscription with your endpoint URL
2. Store the secret from this response — it is returned only here, never by GET /v1/webhooks or GET /v1/webhooks/{id}. If you lose it, rotate it with POST /v1/webhooks/{id}/rotate-secret.
3. When events occur, Aura sends HTTP POST requests to your URL
4. Verify requests using the X-Aura-Signature header

Security:

• Target URL must use HTTPS (no HTTP allowed)
• Each webhook is signed with HMAC-SHA256
• Use the secret to verify request authenticity

Payload Format:

{
  "event": "call.booked",
  "created_at": "2026-01-17T08:00:00Z",
  "data": { /* event-specific data */ },
  "organization_id": "org_xxx",
  "idempotency_key": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

Signature Verification:

const crypto = require('crypto');
const signature = crypto
  .createHmac('sha256', YOUR_SECRET)
  .update(JSON.stringify(payload))
  .digest('hex');

Retry Policy:

• Failed deliveries are retried 3 times
• Backoff: 1s, 5s, 15s
• Subscriptions with repeated failures may be disabled

Exactly-once processing (idempotency_key):

• Every envelope carries an idempotency_key that is stable across retries of the same event. If your endpoint commits its side effect then crashes before returning 2xx, the redelivery carries the same key.
• Enforce exactly-once by adding a (subscription_id, idempotency_key) unique constraint on your side and dropping the row on conflict.
• The key is inside the signed body, so the HMAC signature covers it.

curl -X POST "https://api.aura-app.ai/v1/webhooks" \  -H "Content-Type: application/json" \  -d '{    "event_type": "call.booked",    "target_url": "https://api.example.com/webhooks/aura"  }'

{
  "data": {
    "created_at": "2026-01-17T08:00:00Z",
    "event_type": "call.booked",
    "event_types": [
      "call.booked",
      "call.completed"
    ],
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "target_url": "https://api.example.com/webhooks/aura",
    "secret": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
  },
  "success": true
}

{
  "code": "WEBHOOK_NOT_FOUND",
  "error": "Webhook subscription not found",
  "success": false
}

{
  "code": "WEBHOOK_NOT_FOUND",
  "error": "Webhook subscription not found",
  "success": false
}