> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gamecart.gg/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Configure signed order events from the Gamecart dashboard

Gamecart can deliver order events to an HTTPS endpoint that you control. Webhooks are outbound notifications from Gamecart to your application.

Webhook delivery requires a store plan with the `WEBHOOK` feature.

## Before you begin

You need:

* A public HTTPS endpoint that can receive `POST` requests.
* Access to the Gamecart dashboard.
* Permission to manage integrations for the store.
* A plan that includes webhooks.
* A place to store the webhook secret securely.

Your endpoint should respond quickly. Do any slow work asynchronously after you accept the event.

## Add a webhook endpoint in the dashboard

<Steps>
  <Step title="Open the integrations area">
    In the dashboard, select your store and open **Integrations**.
  </Step>

  <Step title="Open Webhooks">
    Choose **Webhooks** from the integrations menu.
  </Step>

  <Step title="Create an endpoint">
    Click **Create endpoint** and enter a clear name, such as `Production order worker`.
  </Step>

  <Step title="Enter the destination URL">
    Paste your public HTTPS webhook URL. Gamecart validates external URLs before saving or delivering events.
  </Step>

  <Step title="Choose events">
    Select the order events your application needs. Start with the smallest useful set.
  </Step>

  <Step title="Save and copy the secret">
    After saving, copy the webhook secret and store it securely. Gamecart shows it only once.
  </Step>

  <Step title="Send a real test event">
    Place a controlled checkout order and confirm your endpoint receives the expected event and verifies the signature.
  </Step>
</Steps>

## Event types

| Event                     | When it is created                                             |
| ------------------------- | -------------------------------------------------------------- |
| `order.created`           | A checkout order is created and finalized with a redirect URL. |
| `order.payment_approved`  | Payment status changes to `APPROVED`.                          |
| `order.payment_rejected`  | Payment status changes to `REJECTED`.                          |
| `order.payment_cancelled` | Payment status changes to `CANCELLED`.                         |
| `order.payment_refunded`  | Payment status changes to `REFUNDED`.                          |
| `order.payment_dispute`   | Payment status changes to `DISPUTE`.                           |

Manual-order approval events are not sent as seller webhooks.

## Delivery payload

Gamecart sends JSON with this shape:

```json theme={"dark"}
{
  "eventId": "order.payment_approved:GC-7K9Q2X",
  "eventType": "order.payment_approved",
  "createdAt": "2026-06-27T13:05:00",
  "order": {
    "orderId": "GC-7K9Q2X",
    "paymentStatus": "APPROVED",
    "gatewayType": "STRIPE",
    "amount": 19.99,
    "currency": "USD"
  }
}
```

`eventId` is stable for the order and event type. Use it as your idempotency key.

## Delivery headers

```http theme={"dark"}
Content-Type: application/json
User-Agent: Gamecart-Webhooks/1.0
Gamecart-Event-Id: order.payment_approved:GC-7K9Q2X
Gamecart-Event-Type: order.payment_approved
Gamecart-Signature: t=1782565500,v1=<hex_hmac_sha256>
```

See [Webhook signatures](/webhooks/signatures) for verification.

## Review delivery logs

Use the **Deliveries** view for an endpoint to inspect recent attempts. Each delivery shows the event id, event type, status, attempt count, last HTTP status, last error, and next retry time when applicable.

Delivery statuses are:

| Status    | Meaning                                                                              |
| --------- | ------------------------------------------------------------------------------------ |
| `PENDING` | Gamecart has not delivered the event successfully yet, or it is waiting for a retry. |
| `SENT`    | Your endpoint returned a `2xx` response.                                             |
| `FAILED`  | Gamecart exhausted all retry attempts.                                               |

## Retries

Gamecart treats any `2xx` response as delivered.

For non-`2xx` responses, network failures, or invalid targets, Gamecart records the attempt and retries up to `5` attempts. Retry delay is `attemptCount * 5` minutes after each failed attempt.

If your endpoint receives the same `eventId` more than once, process it once and return `2xx` for later duplicates.