--- title: "Webhooks" description: "Understand Inttegro's webhook status today and the recommended alternatives for status updates, reconciliation, and automation." canonical: "https://studio.inttegro.com/api/webhooks" format: inttegro-machine-docs/v1 language: "TypeScript" sdk_version: "v12.0.0" reader_profile: optional reader_manifest: "https://studio.inttegro.com/machine/typescript/readers/index.json" reader_identification: "Optional: declare your client only if known and your current-session capabilities; use reader_manifest for supplemental recommendations." preamble_estimated_tokens: 462 model_token_report: "https://studio.inttegro.com/machine/token-report.json" preamble_questions: 5 preamble_source: "machine-only-decisions" recommended_mcp_tools: [] estimated_tokens: 2690 token_estimate_method: "utf8_bytes_divided_by_4" --- ## Machine preamble **Summary:** Understand Inttegro's webhook status today and the recommended alternatives for status updates, reconciliation, and automation. This TypeScript representation uses the selected SDK's native names wherever Studio has a verified mapping. ### Five questions #### Q1. Is Webhooks the right source for this task? Use this reference for understand inttegro's webhook status today and the recommended alternatives for status updates, reconciliation, and automation. Keep the four decision rules below with its exact operations and fields; do not infer a broader workflow from endpoint order. #### Q2. What is the first decision rule for design state convergence without a merchant webhook? Persist the resource ID and state returned by every write. For one object, refresh through its lookup endpoint; for missed or operational work, use the resource's page endpoint in a bounded reconciliation job. #### Q3. What is the second decision rule for design state convergence without a merchant webhook? A customer-return page is not proof of payment success. Read the latest order or payment state before granting fulfillment, access, or credit. #### Q4. What is the third decision rule for design state convergence without a merchant webhook? Poll only for a bounded user-facing window, then show a pending state and let reconciliation continue. Make every write in that workflow idempotent so a timeout or retry cannot create a duplicate business action. #### Q5. What is the fourth decision rule for design state convergence without a merchant webhook? Provider callbacks mentioned in internal processing are not a public integration surface. Do not build or wait for an undocumented callback URL. If merchant webhooks become available later, still treat delivery as a cue to retrieve canonical resource state. ## Document content # 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. ## Design state convergence without a merchant webhook The four decision rules are in the machine preamble above. ## 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](https://studio.inttegro.com/machine/typescript/inttegro-mcp.md) 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](https://studio.inttegro.com/machine/typescript/api/orders.md#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](https://studio.inttegro.com/machine/typescript/api/refunds.md#lookup-a-refund) | Refund processing is asynchronous; lookup returns the current lifecycle state. | | Whether a payout settled | [Lookup a payout](https://studio.inttegro.com/machine/typescript/api/payouts.md#lookup-a-payout) | Payout execution can move through scheduled, processing, succeeded, failed, or canceled states. | | What changed in the balance | [Page through balance transactions](https://studio.inttegro.com/machine/typescript/api/balance-transactions.md#page-through-balance-transactions) | Balance transactions are the audit trail for debits, credits, payouts, and reconciliation. | | Whether a customer message delivered | [Lookup chime](https://studio.inttegro.com/machine/typescript/api/chimes.md#lookup-chime), [Lookup a scheduled chime](https://studio.inttegro.com/machine/typescript/api/chimes.md#lookup-a-scheduled-chime), or [Lookup a broadcast](https://studio.inttegro.com/machine/typescript/api/chimes.md#lookup-a-broadcast) | Communication APIs expose their own delivery and lifecycle records. | | Whether an OTP flow completed | [Lookup OTP transaction](https://studio.inttegro.com/machine/typescript/api/otps.md#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](https://studio.inttegro.com/machine/typescript/api/orders.md#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](https://studio.inttegro.com/machine/typescript/api/refunds.md#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](https://studio.inttegro.com/machine/typescript/api/payouts.md#lookup-a-payout) for execution status; - for settlement or accounting reports, page through [balance transactions](https://studio.inttegro.com/machine/typescript/api/balance-transactions.md#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](https://studio.inttegro.com/machine/typescript/api/idempotency.md) 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.