> For the complete documentation index, see [llms.txt](https://support.ordereazi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://support.ordereazi.com/developers/webhooks/api-reference.md).

# API Reference

## 🌐 Webhook API Reference

The webhook API provides three endpoints for managing webhooks on your OrderEazi instance: list all registered webhooks, create a new webhook, and delete an existing one.

### 🔑 Authentication

All webhook API requests must include your API key in the `X-OrderEazi-Key` header. Listing webhooks requires the `Read_Administrative_Data` permission. Creating and deleting webhooks require the `Write_Administrative_Data` permission.

> You can generate an API key with the appropriate permissions from the **Settings - API Keys** page in your OrderEazi instance.

### 📋 List Webhooks

**Endpoint:** `GET /api/webhook/list`

**Permission:** `Read_Administrative_Data`

**Response:** Returns all registered webhooks.

```bash
curl -X GET "https://your-instance.ordereazi.com/api/webhook/list" \
  -H "X-OrderEazi-Key: your-api-key-here"
```

```json
{
  "Success": true,
  "Warnings": [],
  "Data": [
    {
      "Id": 12,
      "Created": "2024-11-01T09:00:00",
      "Modified": "2024-11-01T09:00:00",
      "WebhookProcess": "OrderDispatched",
      "Url": "https://example.com/webhook/dispatched",
      "Application": "MyIntegrationApp"
    },
    {
      "Id": 13,
      "Created": "2024-11-02T10:30:00",
      "Modified": "2024-11-02T10:30:00",
      "WebhookProcess": "GRVCompleted",
      "Url": "https://example.com/webhook/grv",
      "Application": null
    }
  ]
}
```

### ➕ Create Webhook

**Endpoint:** `POST /api/webhook`

**Parameters:**

| Parameter | Type   | Description                                                |
| --------- | ------ | ---------------------------------------------------------- |
| `process` | int    | The `WebhookProcess` enum value identifying the event type |
| `url`     | string | The HTTPS endpoint that will receive webhook payloads      |

**Permission:** `Write_Administrative_Data`

> This endpoint is idempotent - creating a webhook with the same `process` and `url` combination as an existing one is a no-op. If the request comes from an installed app, OrderEazi automatically associates the webhook with that app's `InstalledApplicationId`.

```bash
curl -X POST "https://your-instance.ordereazi.com/api/webhook?process=3&url=https://example.com/webhook/dispatched" \
  -H "X-OrderEazi-Key: your-api-key-here"
```

```json
{
  "Success": true,
  "Warnings": [],
  "Data": {
    "Id": 14,
    "Created": "2025-01-15T14:22:00",
    "Modified": "2025-01-15T14:22:00",
    "WebhookProcess": "OrderDispatched",
    "Url": "https://example.com/webhook/dispatched",
    "Application": null
  }
}
```

### ❌ Delete Webhook

**Endpoint:** `DELETE /api/webhook`

**Parameters:**

| Parameter   | Type | Description                     |
| ----------- | ---- | ------------------------------- |
| `webhookId` | long | The ID of the webhook to delete |

**Permission:** `Write_Administrative_Data`

> Use the List Webhooks endpoint to find the `Id` of the webhook you want to remove.

```bash
curl -X DELETE "https://your-instance.ordereazi.com/api/webhook?webhookId=14" \
  -H "X-OrderEazi-Key: your-api-key-here"
```

```json
{
  "Success": true,
  "Warnings": [],
  "Data": true
}
```

If the webhook ID does not exist, the response will have `Success: false` and a warning message.

```json
{
  "Success": false,
  "Warnings": [
    { "Message": "Webhook not found" }
  ],
  "Data": false
}
```

### 📦 Response Format

All endpoints return a `BaseApiResponse` wrapper with the following fields:

| Field      | Type            | Description                                                                         |
| ---------- | --------------- | ----------------------------------------------------------------------------------- |
| `Success`  | bool            | `true` if the operation completed successfully, otherwise `false`                   |
| `Data`     | object or array | The result of the operation, or `null` if the operation failed                      |
| `Warnings` | array           | A list of warning messages encountered during the operation - empty array when none |

A successful response uses HTTP 200. A failed response uses HTTP 400.

### ✅ Summary

* All three endpoints are available on both API v1 and v2 (`/api/v1/webhook/...` and `/api/v2/webhook/...`)
* Use `Read_Administrative_Data` permission to list webhooks; use `Write_Administrative_Data` to create or delete them
* The `process` parameter on the Create endpoint accepts the integer value of the `WebhookProcess` enum - see the Event Catalogue page for the full list of values
* Creating a duplicate webhook (same process and URL) is safe and returns the existing webhook
* Use the `Id` field from the List response to target a specific webhook for deletion