Webhooks

Ingo delivers real-time updates to your configured webhook endpoint as events occur — recipient engagement, identity screening, payment outcomes, and session activity. The connection is one-way: Ingo posts to you. Your endpoint acknowledges receipt with a 2xx response, and the event payload is the authoritative record for everything that follows. Every Ingo product fires webhooks. Event types, payload schemas, and correlation fields differ per product — the setup and verification requirements below apply to all of them.

---

​

Endpoint Requirements

Register a static HTTPS endpoint with your Ingo integration manager before onboarding. Ingo posts webhook payloads as JSON to that URL on every qualifying event.

---

​

TLS Requirements

Your endpoint must support at least one cipher suite from the lists below. TLS 1.3 TLS 1.2

---

​

IP Allowlist

Add the following Ingo IP addresses to your allowlist so webhook traffic can reach your endpoint.

---

​

Delivery Retries

A delivery is successful only when your endpoint returns a 2xx status within 60 seconds. Anything else — a 4xx, a 5xx, a timeout, a TLS handshake failure, or a refused connection — is treated as a failed delivery and queued for retry.

​

Defaults by platform

Retry behavior is configured per endpoint, so the values below are defaults rather than fixed limits. If your program needs a tighter schedule for time-sensitive events or a longer window to absorb maintenance, raise it with your integration manager during onboarding. Once the retry window is exhausted, the event is not redelivered automatically. There is no self-service replay — recovery after the window closes requires an Ingo support request. Final transaction status is always available in your daily SFTP reporting regardless of webhook delivery outcome.

​

Planned maintenance

If you know in advance that your endpoint will be unavailable — a deployment, a certificate rotation, an infrastructure migration — notify your Ingo account coordinator ahead of time. Ingo can support a maintenance window so events are held rather than burning retry attempts against an endpoint you already know is down. This cannot be applied retroactively.

---

​

Handling Events

Acknowledge first, persist, then process. Return a 2xx as soon as you have written the raw payload to durable storage — a queue, an event table, a log. Perform validation, enrichment, and downstream work asynchronously after acknowledging. This matters for two reasons:

• Handlers that hold the connection open while processing risk hitting the 60-second timeout, which produces a retry and a duplicate delivery.
• Accepting an event should be independent of your ability to process it downstream. If internal processing later fails — a bad deploy, a downstream outage, a mapping defect — a retained copy of the payload lets you reprocess on your own schedule, with no dependency on Ingo replaying events beyond the configured retry window.

Design for idempotency. The same event may arrive more than once. Use the unique event identifier as your deduplication key — the field differs by platform, so see Defaults by platform above. Persist the identifier and discard any event whose identifier you have already accepted. Deduplicate at two levels. Delivery and outcome are separate concerns. metadata.id deduplicates the event — whether you have already accepted this delivery. participant_unique_id1 identifies the transaction — which disbursement the event describes. Distinct events with different metadata.id values can describe the same payment, so key your event log on metadata.id and your payment ledger on participant_unique_id1. Reconciling a ledger on metadata.id alone will double-count. A returned payment stays returned. returned is a terminal outcome for a disbursement. Once you receive a return event for a transaction, treat that payment as returned and do not reopen it on the strength of a later event referencing the same participant_unique_id1. Terminal outcomes are not superseded by subsequent status events — apply the terminal state and reconcile anything that appears to contradict it rather than overwriting. The API response is the source of truth. Webhooks are an optional subscription layer for real-time status updates — they do not supersede the synchronous response. All transaction statuses, regardless of payment type, are always reflected in your daily SFTP reporting.

---

​

Testing During Development

Webhook endpoints are registered by your Ingo integration manager — there is no self-service portal to update the URL your program is configured to call. Before beginning sandbox development, confirm your endpoint URL with your integration manager so it can be registered as part of your program setup. If you need to receive webhooks on a local development machine, use a tunnel tool that provides a persistent, stable URL — a fixed subdomain or custom domain that does not change between sessions. Register that stable URL with your integration manager once. Ephemeral tunnels that generate a new URL on every restart require a configuration change with your integration manager each time, which is not practical for active development.

---

​

Webhook References

Event types, payload schemas, retry behavior, and signature details are documented per product.