account.import.failed

An account import stopped before finishing. reason says why — e.g. needs_permissions (the host must grant access; GET /v1/connect carries a fixUrl), duplicate_account, or stalled (no progress for too long). counts has what did import.

Payload

Every delivery uses the same outer envelope (event, eventId, apiVersion, timestamp, data). Dedupe on eventId — it stays stable across retries and replays, while the X-Repull-Delivery-Id header changes on every attempt.

{
  "event": "account.import.failed",
  "eventId": "3f1c9a2e-8b7d-4c6a-9e0f-1a2b3c4d5e6f",
  "apiVersion": "2026-04",
  "timestamp": "2026-05-01T12:34:56.000Z",
  "data": {
    "importId": "7f0c2a9e-3b1d-4c55-9a8e-2d6f1b0c4e71",
    "trigger": "connect",
    "status": "failed",
    "outcome": null,
    "startedAt": "2026-10-16T18:24:19.000Z",
    "completedAt": "2026-10-16T18:24:51.000Z",
    "stages": [
      {
        "name": "account",
        "expected": 1,
        "done": 0,
        "failed": 0
      }
    ],
    "counts": {},
    "reason": "needs_permissions"
  }
}

Verifying signatures

Every delivery includes a timestamped X-Repull-Signature header of the form t=<unix_ts>,v1=<hex>, where v1 is HMAC-SHA256(signing_secret, `${t}.${raw_body}`). Verify it before processing — see Verify Signatures for full Node.js and Python examples.

Use the raw body

Sign the raw request body exactly as received, not a re-stringified JSON object. Re-serialisation can reorder keys or change whitespace and break the signature.

Tip: Acknowledge with a 2xx status within 10 seconds. Failed deliveries are retried 7 times over 24 hours, with backoff.Webhook reliability →

AI