# How Forage Webhooks Work

Understand what webhooks are, when events fire, and how Forage delivers them

<GuideNavTop
  guideName="Webhooks Guide"
  pages={[
    { slug: "configure-webhooks", title: "Overview", description: "Guide overview, audience, and prerequisites" },
    { slug: "webhooks-concepts", title: "How Webhooks Work", description: "What triggers events, how delivery works, and terminal states" },
    { slug: "webhooks-configure", title: "Configure Webhooks", description: "Set up an endpoint, register in the dashboard, and verify signatures" },
    { slug: "webhooks-event-reference", title: "Event Reference", description: "Specs for all event types, payload schemas, and IP addresses" }
  ]}
  currentIndex={1}
/>

## 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.

```mermaid
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   |

```mermaid
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](./webhooks-event-reference.md).

## 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.

## Related documentation

* [How to Configure Webhooks](./webhooks-configure.md). Set up an endpoint, register it in the dashboard, and verify signatures.
* [Reference: Webhook Events](./webhooks-event-reference.md). Specs for all event types, payload schemas, field definitions, and IP addresses.
* [EBT Payments 101](https://docs.joinforage.app/docs/ebt-online-101). Background on how EBT payment processing works with Forage.