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 (pending_mfa):

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)

Bank Consent Events:

bank.revocation - Emitted when a user's bank consent is revoked. Payload includes client_id, user_id, connection_id (same as user_id), account_id, and status "revoked". We recommend to notify end-user to reconnect their bank.

Note: Bank revocation notifications are only available for certain banks (like Bank of America and PNC) as we rely on the banks themselves to send this notification.

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

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