Webhooks

Araucaria uses webhooks to notify your application when events happen in real-time. Instead of polling the API, you receive HTTP POST requests whenever connection status changes or account data is updated.

How Webhooks Work

An event occurs (e.g., connection.connected)
Araucaria sends an HTTP POST to your configured endpoint
Your server verifies the signature
Your server processes the event
Your server returns a 2xx response

Key Features

Feature	Description
HMAC Signing	All webhooks are signed with HMAC-SHA256 for verification
At-Least-Once Delivery	Events are guaranteed to be delivered at least once
Automatic Retries	Failed deliveries are retried with exponential backoff
Idempotency	Events include a unique ID for deduplication

Webhook Payload

All webhooks are sent as HTTP POST requests with a JSON body:

json

              {
  "id": "evt_01HXYZ123ABC456DEF789GHI",
  "type": "connection.connected",
  "created_at": "2026-01-20T14:30:00.000Z",
  "data": {
    "eventId": "evt_01HXYZ123ABC456DEF789GHI",
    "type": "connection.connected",
    "occurredAt": "2026-01-20T14:30:00.000Z",
    "clientId": "cli_01H8X9KQWERTY12345",
    "connectionId": "conn_01H8X9ABCDEF67890",
    "previousStatus": "verifying"
  }
}
            

Request Headers

Header	Description
Content-Type	`application/json`
Araucaria-Signature	HMAC signature for verification

⚠️ Important

Always verify webhook signatures before processing events. See Signature Verification for details.