---
updatedAt: 2026-11-17T18:17:46.000Z
agentTools:
  projectIndex: https://docs.cartai.ai/llms.txt
---

# Webhooks

CartAI uses webhooks to push real-time event notifications to your server. Instead of polling the API on a schedule, your application receives an HTTP `POST` from CartAI the moment something changes — making webhooks the recommended primary integration pattern.

This page covers the general setup that applies to all CartAI webhooks. For the events and payloads specific to each API, see that API's webhook documentation.

***

## How CartAI Webhooks Work

1. You expose a public HTTPS endpoint on your server.
2. You register that endpoint in the **CartAI Admin Portal**, along with how CartAI should authenticate to it.
3. Whenever a relevant event occurs, CartAI sends an HTTP `POST` request to your endpoint with a JSON body describing the event.
4. Your endpoint validates the request, responds with a `2xx` status, and then processes the event.

```
   Event occurs in CartAI
            │
            ▼
   CartAI  POST https://your-server.com/webhook
           Content-Type: application/json
           Authorization: ...
           { ...event payload... }
            │
            ▼
   Your server validates auth  ──►  responds 200 OK
            │
            ▼
   Your server processes the event asynchronously
```

***

## Configuring Webhooks in the Admin Portal

![](https://files.readme.io/e2633c57e9b2c8c22730722b91e10f7929d63003646abd11e8b5dccfb933ab67-Screenshot_2026-11-17_at_2.29.01_AM.png)

Configure your webhook in the **CartAI Admin Portal** under the **Webhooks** module. You will provide:

1. **Endpoint URL** — The public HTTPS URL CartAI will `POST` events to. It must be reachable from the internet.
2. **Authentication** — How CartAI should authenticate its requests to your endpoint (see [Authentication](#authentication)).
3. **Custom headers** — Any additional headers CartAI should include on every event request.

Your endpoint must:

* Be accessible over **HTTPS** — plain HTTP is not accepted in production.
* Accept `POST` requests with a `Content-Type: application/json` body.
* Return a `2xx`**&#x20;HTTP status** within a few seconds of receiving the request (see [Expected Response](#expected-response-from-your-endpoint)).

<br />

***

## Authentication

CartAI supports the following options for authenticating webhook requests to your endpoint. Choose your preferred method when configuring the webhook in the Admin Portal.

### Basic Authentication

CartAI sends a standard `Authorization: Basic <base64(username:password)>` header with every event. Validate this header in your webhook receiver before processing the payload.

```
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
```

### OAuth2

CartAI fetches an access token from your OAuth2 token endpoint before delivering events and includes it as a `Bearer` token. Suitable for integrations where your webhook endpoint is already part of an OAuth2-protected API.

```
Authorization: Bearer <access_token>
```

### Custom Headers

Add any arbitrary key-value header pairs that CartAI will include on every event request — for example, a shared secret header your server validates:

```
X-CartAI-Secret: your-shared-secret-value
```

### No Authentication *(testing only)*

Webhooks can be configured without any authentication for local development and testing. **Do not use this in production** — without authentication, any party that discovers your webhook URL can send fake events to your server.

### Validating requests

* **Validate the authentication header before processing any payload.** Reject requests that fail validation with a `401 Unauthorized`.
* **Use HTTPS only.** Never accept webhook deliveries over plain HTTP in production.

***

## Expected Response from Your Endpoint

**Respond with a&#x20;**`2xx`**&#x20;status immediately.** CartAI expects a quick acknowledgement. If your handler performs slow work — database writes, downstream API calls, email sends — do that work *after* you've sent the response.

| Your response                                  | How CartAI treats it                |
| ---------------------------------------------- | ----------------------------------- |
| `2xx` within a few seconds                     | Delivered successfully.             |
| Non-`2xx` status, timeout, or connection error | Delivery failed — CartAI may retry. |

A simple acknowledgement is sufficient:

```javascript
// Express.js example
app.post("/webhook", (req, res) => {
  // ✅ Validate authentication first
  if (!isAuthorized(req)) {
    return res.status(401).end();
  }

  // ✅ Acknowledge immediately
  res.status(200).json({ received: true });

  // ✅ Then do your work asynchronously
  processEvent(req.body).catch(console.error);
});
```

### Handling retries

Because CartAI may retry failed deliveries, the same event can arrive more than once. Make your handler **idempotent** — record which events you have already processed and skip duplicates. Use the identifying fields documented for each webhook's payload as the deduplication key.

### Best practices

* **Acknowledge before processing.** Sending `200` first prevents unnecessary retries when your processing is slow.
* **Make your handler idempotent.** Expect occasional duplicate deliveries.
* **Log all incoming events.** Store the full raw payload for each event to keep an audit trail and simplify debugging.