Webhooks — Delivery Reliability

Webhooks are the primary mechanism through which integrations communicate events and state changes from financial providers back to the Toqio platform. This section defines the reliability contract integrations are expected to uphold when delivering webhooks to Toqio, and describes the platform behaviours that support reliable end-to-end delivery.

🔒
All webhook calls must be delivered over HTTPS and authenticated as described in the Authentication section. Unauthenticated or unencrypted webhook calls will be rejected.

Delivery direction

Webhooks in the Integration Hub flow from the integration layer toward Toqio. The integration is responsible for:

Receiving events or state changes from the financial provider.
Translating them into the Toqio webhook contract.
Delivering them reliably to the Toqio webhook endpoint.

Toqio does not poll the integration for state. The webhook is the authoritative channel for communicating asynchronous events.

Retry policy

Integrations are expected to implement a retry policy that ensures delivery during periods of transient unavailability on Toqio's side. The specific parameters of the retry policy — including maximum retry window, number of attempts, and backoff configuration — are defined collaboratively during the onboarding process based on the criticality and nature of the integration scenario.

As a general principle, retry policies should apply exponential backoff with jitter to avoid thundering herd effects during recovery periods. The retry window should be sufficiently large to tolerate meaningful instability periods without resulting in event loss.

Exponential backoff with jitter — reference pattern:

wait_time = min(cap, base * 2^attempt) + random_jitter

Where:
  base     — initial wait interval (e.g. 1 second)
  cap      — maximum wait interval (e.g. 5 minutes)
  attempt  — zero-based retry attempt count
  jitter   — random value within [0, wait_time * jitter_factor]

Toqio responds with standard HTTP status codes to communicate delivery outcome:

HTTP Status	Meaning	Action
`2xx`	Webhook accepted	No retry needed
`4xx` (except `429`)	Malformed request or contract violation	Do not retry — investigate payload
`429`	Rate limit exceeded	Retry with backoff, respect `Retry-After` header if present
`5xx`	Toqio transient error	Retry with exponential backoff
Timeout / no response	Network or availability issue	Retry with exponential backoff

Definitive delivery failure

When the retry window is exhausted without a successful delivery acknowledgement, the event should be treated as a definitive delivery failure. Integrations should log these events with full payload context to support post-incident reconciliation.

On Toqio's side, delivery failures are surfaced through the platform's observability layer, which provides visibility into unacknowledged webhook events and supports incident investigation and manual recovery where needed.

Idempotency

Network instability and retry logic can result in Toqio receiving the same webhook more than once. Integrations must design for this by ensuring that each webhook delivery carries a stable, unique identifier that Toqio can use to detect and safely discard duplicate deliveries.

X-Toqio-Idempotency-Key header

The integration must include an idempotency key on every webhook request using the following header:

X-Toqio-Idempotency-Key: {idempotency_key}

Requirements for the idempotency key:

Must be unique per logical event — not per delivery attempt. All retry attempts for the same event must carry the same idempotency key.
Must be a string of sufficient entropy to avoid collisions across integrations and time. A UUID v4 is the recommended format.
Must remain stable for the full duration of the retry window for that event.

Example:

POST /webhooks
Content-Type: application/json
X-Api-Key: {your_api_key}
X-Toqio-Idempotency-Key: 7f3e2a1b-94c0-4d8e-b6f5-2c1a0e9d3f7b

{
  "webhookType": "SAVE_TRANSACTION",
  ...
}

When Toqio receives a webhook with an X-Toqio-Idempotency-Key that matches a previously acknowledged delivery, the request is acknowledged without reprocessing the payload. The response code and body will match the original successful response.

📘
Idempotency key deduplication operates within a rolling retention window. Keys outside this window are no longer guaranteed to be retained. The exact retention period is defined during onboarding based on the integration's retry window configuration.

Event ordering

Toqio does not guarantee that webhooks will be received in the order they were emitted. Network conditions, retry delays, and distributed system behaviour can result in out-of-order delivery.

Integrations and their corresponding adapter implementations should account for this explicitly:

Use timestamps over sequence assumptions. Payload fields such as date and creationDate should be used to determine the logical order of events, not the order of HTTP delivery.
Apply last-write-wins based on event timestamp where state transitions are involved (e.g. SYNC_TRANSACTION_STATUS), discarding updates that are logically older than the current known state.
Design state machines defensively. A webhook representing a final state (e.g. SETTLED) may arrive before an intermediate state (e.g. PENDING). The integration should not reject or fail on unexpected state transitions — it should apply the most recent state and log the anomaly.

Payload stability

Each webhook type defines a versioned contract. Fields documented as mandatory will remain stable within a version. Optional fields may be added in a non-breaking manner. Integrations should be implemented to tolerate the presence of unknown fields without failing.

Breaking changes to webhook payloads are communicated in advance through the integration changelog and are introduced following the versioning policy described in the API Versioning section.

Observability and diagnostics

For active monitoring and incident investigation, Toqio's observability platform provides visibility into webhook delivery activity, including delivery status, retry history, and failure context. Access and configuration details are established during onboarding.

Integrations are strongly encouraged to implement equivalent observability on their side — logging each delivery attempt with its outcome, the idempotency key, the event timestamp, and sufficient payload context to support reconciliation without requiring full payload storage.

Environments

To start working with the webhooks service, ask the delivery team to create your service as defined in this page. Once set up, you can start making requests to update objects.

Send requests to the following URLs based on your target environment:

Environment	URL
Sandbox	`https://core.sandbox.toq.io/webhooks/integration/{INTEGRATION}/webhookType/{WEBHOOK_TYPE}`
Production	`https://core.toq.io/webhooks/integration/{INTEGRATION}/webhookType/{WEBHOOK_TYPE}`

Replace {INTEGRATION} with your integration identifier and {WEBHOOK_TYPE} with the specific webhook type you want to invoke.