Statement-bundle webhooks

Contact Us to discuss non-production testing and access options.

Every event is recorded in a durable outbox in the same database transaction as the change that caused it, so a committed change always has its event. A background dispatcher then delivers it. A delivery succeeds when your receiver answers with any 2xx status within 15 seconds; anything else (a non-2xx status, a timeout, a connection error) fails that attempt.

• At least once. The same event can arrive more than once, for example when your 2xx response is lost. Use X-OptiTrust-Event-Id (also eventId in the body) as the idempotency key.
• No ordering guarantee. Events can arrive out of order, especially around retries. occurredAtUtc orders the changes that triggered events; it is not a version of the payload. Fetch the bundle from the API when you need its current state.
• Current state, historical trigger. The bundle and file objects describe the state when the event is sent, not when it happened; event, changeKind and occurredAtUtc describe what happened and when.
• Unsafe or unsigned destinations fail at once. A URL that is not public HTTPS, or a destination without a signing secret, fails the event without retrying. Events with no destination configured are not sent.

Times are approximate: the dispatcher runs every minute. After the tenth failed attempt the event is not retried; fetch the bundle from the API to reconcile.

Bundle responses expose up to the 10 most recent webhook delivery entries, with dateUtc, status (delivered or failed), and detail. The detail names the event, its ID, the attempt number, the failure code (for example http_503 or timeout) and which secret signed it (bundle or account-v2), never a secret value.

Send an HTTPS URL in the bundle API request. A blank value disables the bundle's own callbacks. On update, omit webhookUrl (or send null) to keep the existing URL and secret; changing the URL keeps the same secret.

The bundle's webhookSecret is returned only by the response that generated it: the 201 Created create response (and its 200 replay with the same Idempotency-Key), or the update response that first set a webhookUrl. Every other response, including GET, the bundle list and file completion, returns webhookSecret: null. Store the secret when you receive it.

{
  "idnumber": "8001015009087",
  "type": "TransactionExtraction",
  "dateRange": "Last90Days",
  "proofOfAccount": "NotNeeded",
  "webhookUrl": "https://client.example.com/optitrust/webhooks"
}

Tenant administrators can set an account-level bundle webhook in the OptiTrust workspace, on the company details page under Bundle webhooks. It receives events for every bundle in the account, including bundles created in the workspace or by email. A webhookUrl set on an individual bundle overrides it, and that bundle's events are signed with the bundle's own webhookSecret.

The account signing secret is shown once, on the page that generated it, and never again. Rotate it in two steps so no delivery fails verification:

1. Generate a new secret. It is pending: deliveries are still signed with the active secret. Configure your receiver to accept both.
2. Activate the pending secret. Deliveries from then on are signed with it. Remove the old secret from your receiver once in-flight retries have drained.

A pending secret can be replaced before activation; the one shown earlier then cannot be activated. The URL can only be set once a secret is active. Each payload carries account.id, a stable public identifier for your account, so one receiver can serve several OptiTrust accounts.

• X-OptiTrust-Event-Id contains the idempotency key for this delivery.
• X-OptiTrust-Event contains the event name.
• X-OptiTrust-Timestamp contains the Unix timestamp in seconds.
• X-OptiTrust-Signature contains sha256=<hex>.

Compute HMAC-SHA256 over this UTF-8 string, using the bundle webhookSecret when the bundle has its own webhookUrl, or else your account signing secret, then compare it with the signature header using a constant-time comparison:

{timestamp}.{eventId}.{rawJsonBody}

X-OptiTrust-Timestamp is the time of this attempt, so a retried delivery carries a fresh timestamp. Reject unsigned requests and stale timestamps, and treat a repeated event ID as already processed. Return any 2xx response only after the payload has been accepted.