Events you can subscribe to

Job lifecycle events (consolidated - recommended)

job.balance - Balance refresh job notifications (all statuses)
job.transaction - Transaction history job notifications (all statuses)
job.identity - Identity job notifications (all statuses)

Job Status Values (included in webhook payload):

initiated - Job has been created and started
in_progress - Job is currently being processed
pending_mfa - Job requires MFA authentication
completed - Job finished successfully
failed - Job encountered an error and failed

Note on which statuses we send as webhooks:

We emit webhooks for initiated, pending_mfa, completed, and failed.

We do not send a separate webhook for in_progress; it’s an internal/transient state.

MFA Flow:

Some jobs may require multi-factor authentication. You'll receive a webhook with status pending_mfa and should prompt the user to complete MFA in the widget UI. After MFA completion, you'll receive the final completed/failed webhook.

Migration Tool Events:

migration_tool - Migration process notifications (all statuses)

Migration Status Values (included in webhook payload):

initiated - Migration job has been started and CSV file has been processed into SQS queue
completed - Migration job finished processing all records (all items have been processed)

Other events:

test.event (for connectivity testing)

Notes

We may add new event types in the future. Your handler should ignore unknown fields.

Delivery Request Format

Content-Type: application/json
User-Agent: Aerosync-Webhooks/1.0
X-Webhook-Signature: sha256=...  (present only if you set secret_key)

{
    "event": "job.transaction",
    "timestamp": 1700000000,           // Unix timestamp (seconds)
    "merchant_id": "your_merchant_id",
    "data": {
      /* event-specific object with status field indicating job state */
      "status": "completed"  // or "initiated", "in_progress", "pending_mfa", "failed"
    }
}

Idempotency and ordering

At-least-once delivery: you may receive duplicates; make processing idempotent
Ordering is not guaranteed across different subscriptions or retries
Respond quickly with 2xx on success; non-2xx or >30s timeout triggers retry

Retries and pausing

Up to 3 delivery attempts per event (exponential backoff, capped at 60s)
After 5 consecutive failures, the subscription is auto-paused; no further deliveries until unpaused