# 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://support.ordereazi.com/developers/webhooks/api-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.