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

# Eaglecart Webhooks: Real-Time HTTP Event Notifications

> Register Eaglecart webhooks to receive real-time event notifications. Learn request headers, HMAC-SHA256 signature verification, and automatic retries.

Eaglecart can send real-time HTTP notifications to your server whenever events occur in your store. Instead of polling the API for changes, you register a webhook endpoint and Eaglecart pushes a JSON payload to your URL the moment an event fires — keeping your integrations fast, reliable, and up to date.

## Registering a Webhook

**1. Open the Webhooks settings**

In your Eaglecart admin, navigate to **Settings → Developer → Webhooks**.

**2. Add a new webhook**

Click **Add webhook** to open the creation form.

**3. Enter your endpoint URL**

Provide the full URL of your server endpoint. The URL **must use HTTPS** — Eaglecart rejects plain HTTP endpoints to protect payload integrity in transit.

**4. Select event topics**

Choose one or more event topics you want to subscribe to (for example, `order.created` or `inventory.low_stock`). You can subscribe to multiple topics on a single endpoint.

**5. Save and verify**

Click **Save**. Eaglecart immediately sends a test ping to your endpoint. Confirm your server responds with a `200 OK` before the dialog closes.

> [!TIP]
>
> During development, use a tunnelling tool like [ngrok](https://ngrok.com) to expose your local server to the internet with a temporary HTTPS URL. Run `ngrok http 3000` and paste the generated URL into the endpoint field.

***

## Webhook Request Format

Every webhook delivery is an HTTP **POST** request sent to your registered endpoint. The request contains the following headers and a JSON body.

### Headers

| Header | Description |
| - | - |
| `X-Eaglecart-Topic` | The event name that triggered the delivery, e.g. `order.created` |
| `X-Eaglecart-Signature` | HMAC-SHA256 signature of the raw request body, base64-encoded |
| `Content-Type` | Always `application/json` |

### Example request

```http Headers theme={null}
POST /webhooks/eaglecart HTTP/1.1
Host: your-server.example.com
Content-Type: application/json
X-Eaglecart-Topic: order.created
X-Eaglecart-Signature: sha256=3dfd8f2b1e4c7a09b56e2f4d8c1a3e7b2f9d4c6a1b8e3f7d2c5a9b4e1f6d3c8
```

```json Body (order.created) theme={null}
{
  "id": "ord_01HXYZ9ABCDEF",
  "created_at": "2024-06-15T10:32:00Z",
  "status": "pending",
  "currency": "USD",
  "total_price": "149.99",
  "customer": {
    "id": "cust_01HXYZ1234567",
    "email": "jane.doe@example.com",
    "first_name": "Jane",
    "last_name": "Doe"
  },
  "line_items": [
    {
      "id": "li_01HXYZ9999999",
      "product_id": "prod_01HXYZ7777777",
      "variant_id": "var_01HXYZ8888888",
      "title": "Classic Wool Sweater",
      "quantity": 1,
      "price": "149.99"
    }
  ],
  "shipping_address": {
    "line1": "123 Maple Street",
    "city": "Portland",
    "state": "OR",
    "zip": "97201",
    "country": "US"
  }
}
```

> [!WARNING]
>
> Your endpoint must return a **2xx HTTP response within 5 seconds** of receiving a delivery. If your handler takes longer than 5 seconds or returns a non-2xx status, Eaglecart marks the delivery as failed and begins the retry sequence. Offload any heavy processing to a background queue and acknowledge the webhook immediately.

***

## Verifying Signatures

Every webhook delivery includes an `X-Eaglecart-Signature` header so you can confirm the request genuinely came from Eaglecart and that the payload was not tampered with in transit.

Eaglecart computes the signature by taking the **HMAC-SHA256** of the raw request body using your webhook's secret key, then base64-encoding the result and prepending `sha256=`.

To verify the signature in your handler:

1. Retrieve the raw, unparsed request body as bytes.
2. Compute `HMAC-SHA256(body, webhookSecret)` and base64-encode the digest.
3. Prefix the result with `sha256=`.
4. Compare your computed value against the `X-Eaglecart-Signature` header using a **constant-time comparison** function to prevent timing attacks.

```javascript Node.js — signature verification theme={null}
const crypto = require('crypto');

function verifyWebhookSignature(rawBody, signatureHeader, secret) {
  // Compute the expected signature
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(rawBody); // rawBody must be a Buffer or raw string, NOT parsed JSON
  const expectedSignature = 'sha256=' + hmac.digest('base64');

  // Use timingSafeEqual to prevent timing attacks
  const expected = Buffer.from(expectedSignature, 'utf8');
  const received = Buffer.from(signatureHeader, 'utf8');

  if (expected.length !== received.length) {
    return false;
  }

  return crypto.timingSafeEqual(expected, received);
}

// Express.js example — use express.raw() to get the raw body
app.post('/webhooks/eaglecart', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-eaglecart-signature'];
  const secret = process.env.EAGLECART_WEBHOOK_SECRET;

  if (!verifyWebhookSignature(req.body, signature, secret)) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(req.body);
  const topic = req.headers['x-eaglecart-topic'];

  // Acknowledge immediately, then process asynchronously
  res.status(200).send('OK');

  processWebhookAsync(topic, event);
});
```

> [!NOTE]
>
> Find your webhook secret key on the webhook detail page in **Settings → Developer → Webhooks**. Rotate it at any time — Eaglecart will begin signing with the new secret immediately, so update your server before rotating.

***

## Retries

If your endpoint fails to respond with a 2xx status within 5 seconds, Eaglecart automatically retries the delivery up to **5 times** using exponential backoff. Retry attempts are spaced over a **24-hour window**:

| Attempt | Delay after previous failure |
| - | - |
| 1st retry | 5 minutes |
| 2nd retry | 30 minutes |
| 3rd retry | 2 hours |
| 4th retry | 6 hours |
| 5th retry | 16 hours |

After the fifth failed attempt, Eaglecart marks the delivery as permanently failed. You can view the delivery history and manually replay any failed delivery from **Settings → Developer → Webhooks → \[your webhook] → Delivery log**.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.