Webhooks

Inttegro does not expose merchant-facing webhooks today. Your application cannot register a callback URL for order, payment, payout, refund, or message events yet. Build integrations around synchronous API responses, lookup endpoints, and bounded reconciliation jobs.

Current status

Some Inttegro services receive callbacks from payment and delivery providers. Those provider callbacks are internal to Inttegro. They update Inttegro's own records so that your application can read the latest state through the public API.

For your integration, the public contract is explicit reads:

• the response returned by the request you just made;
• lookup endpoints when you have a resource ID;
• page endpoints for reconciliation and back-office review; and
• MCP tools for authenticated AI and operator workflows.

What to use instead

When you need to know	Use	Why
Whether an order was paid	Lookup an order	The order is the durable record for payment state, line items, invoice state, and customer-facing status.
Whether a refund finished	Lookup a refund	Refund processing is asynchronous; lookup returns the current lifecycle state.
Whether a payout settled	Lookup a payout	Payout execution can move through scheduled, processing, succeeded, invalid, or canceled states.
What changed in the balance	Page through balance transactions	Balance transactions are the audit trail for debits, credits, payouts, and reconciliation.
Whether a customer message delivered	Lookup chime, Lookup a scheduled chime, or Lookup a broadcast	Communication APIs expose their own delivery and lifecycle records.
Whether an OTP flow completed	Lookup OTP transaction	OTP state belongs to the OTP transaction, not a background notification.

Payment and checkout flows

For checkout and payment confirmation, make your own application state depend on the resource returned by Inttegro, not on an event you hope arrives later.

Use this pattern:

1. Create or finalize the order and store the returned order.id.
2. If the customer is sent to Inttegro Checkout, include enough local state to resume the session when the customer returns.
3. When your app needs the latest result, call Lookup an order.
4. For a live waiting screen, poll for a short bounded window. Start around every two to five seconds, then back off or stop when the user leaves the flow.
5. Treat terminal states as final. If the state is still in progress after your wait window, show a clear pending state and continue reconciliation in the background.

This keeps the customer experience tied to the order record. It also avoids the failure mode where a customer is charged successfully, but your UI stays stuck because a separate notification did not arrive.

Payouts, refunds, and messages

Use lookup endpoints for a single object you are actively tracking. Use page endpoints for operational review and reconciliation.

For example:

• after creating a refund, store the refund.id and poll Lookup a refund until the refund is terminal or your workflow no longer needs a live answer;
• after scheduling a payout, store the payout.id and use Lookup a payout for execution status;
• for settlement or accounting reports, page through balance transactions rather than reconstructing money movement from order or payout lists; and
• for customer communications, read the Chime, schedule, or broadcast object that represents the message operation you created.

Reconciliation jobs

Most production systems still need background reconciliation, even when a platform offers webhooks. Run a scheduled job that checks the Inttegro records your system cares about and repairs local state when needed.

A practical reconciliation job usually:

• stores Inttegro IDs beside your local records;
• fetches recent records with page endpoints;
• fetches important in-progress records by ID;
• treats Inttegro as authoritative for Inttegro-owned state;
• records when it last checked each object; and
• alerts humans only when a record stays unresolved longer than your business workflow allows.

Use idempotency keys for write operations so retries and reconciliation actions do not create duplicate orders, payments, refunds, or messages.

If Inttegro adds webhooks later

When a merchant webhook surface exists, treat webhook delivery as a notification that something may have changed. Do not treat the webhook payload as the final source of truth for money, fulfillment, or customer access.

The safer pattern will remain:

1. Receive and verify the webhook.
2. Deduplicate it by event ID.
3. Fetch the referenced Inttegro resource by ID.
4. Apply local side effects from the fetched resource state.
5. Make the local side effect idempotent.

That design handles retries, duplicates, delayed delivery, and out-of-order events without corrupting your own state.

If you need a push channel

If polling and reconciliation do not fit your use case, contact Inttegro with a concrete workflow. Include:

• the resource you need to observe;
• the state transition that matters;
• how quickly your system needs to react;
• what goes wrong if the update is delayed;
• the volume of events you expect; and
• whether you already have a secure, observable webhook receiver.

That information helps us decide whether a webhook, dashboard alert, MCP workflow, or another integration surface is the right product shape.