How Forage Webhooks Work

What are webhooks and why use them

You can configure webhooks to send real-time updates of certain Forage events to endpoints that you define.

Webhooks are useful for maintaining state between the front-end and backend of your application.

For example, let's say a customer completes the Forage Checkout UI and is redirected to your website's order confirmation page. This is the typical flow to alert a customer that an order is successful, however, it's possible that the customer closes the client app before the app has a chance to send the response to your backend. Listening for an ORDER_STATUS_UPDATED webhook event ensures that your backend still gets the update and the order is fulfilled.

sequenceDiagram
    participant Customer
    participant Forage
    participant Backend

    Customer->>Forage: Completes checkout
    Forage->>Customer: Redirect to order confirmation
    Customer--xBackend: App closes before response lands

    Note over Backend: Order status never received

    Forage->>Backend: ORDER_STATUS_UPDATED webhook
    Backend->>Backend: Order fulfilled

You can also use webhooks to trigger internal processes. For example, you can listen for a PAYMENT_STATUS_UPDATED webhook to kick off bookkeeping or updating the payment status in your database.

Event states

Every webhook event includes a data.status field. Some states are terminal (the resource won't change again) and some are not. The distinction matters for how you handle retries and downstream processes.

Terminal states

A terminal state means the resource won't change again. Use terminal states to close out your records: fulfill orders, mark refunds complete, update bookkeeping.

succeeded: The operation completed successfully. Always a terminal state.
canceled: The operation was canceled. Always a terminal state.

Non-terminal states

A non-terminal state means the resource can still change. Expect a follow-up event.

failed: The operation failed and may be retried. Not a terminal state for payments, refunds, or orders.

States by event type

Event	`succeeded`	`failed`	`canceled`
`PAYMENT_STATUS_UPDATED`	Terminal	Not terminal	Terminal
`REFUND_STATUS_UPDATED`	Terminal	Not terminal	Terminal
`ORDER_STATUS_UPDATED`	Terminal	Not terminal	Terminal

flowchart LR
    A((start)) --> B[processing]
    B --> C[succeeded ✓]
    B --> D[failed]
    B --> E[canceled ✓]
    D -->|Forage retries| B

For the full list of conditions that trigger each state, see Reference: Webhook Events.

Delivery order

Don't expect to receive webhooks in the same order that they're created. For example, when an order and its associated payments are captured, Forage generates both ORDER_STATUS_UPDATED and PAYMENT_STATUS_UPDATED events. While the payment event is technically generated before an order event, it's possible that the ORDER_STATUS_UPDATED webhook is delivered before PAYMENT_STATUS_UPDATED. Handle webhooks independently of any anticipated delivery order.