# Webhooks API Reference

## Creating a Webhook

To create a new webhook, send a POST request to the webhook endpoint.

### Endpoint

```
POST /api/v2/webhooks
```

### Request Parameters

| Parameter      | Type   | Required | Description                                                                                                       |
| -------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `kind`         | string | Yes      | The type of webhook. Must be one of: `order`, `confirmation_document_available`, `certificate_document_available` |
| `endpoint_url` | string | Yes      | The URL where webhook events will be sent                                                                         |

### Headers

* Authentication is required (based on the controller inheriting from BaseController)

### Request

```bash
curl -X POST \\
  <https://api.squake.earth/v2/webhooks> \\
  -H 'Authorization: Bearer YOUR_API_TOKEN' \\
  -H 'Content-Type: application/json' \\
  -d '{
    "kind": "order",
    "endpoint_url": "<https://your-domain.com/webhook-receiver>"
  }'

```

### Response

### Success (201 Created)

```json
{
    "id": "webhook_id",
    "kind": "order",
    "endpoint_url": "<https://your-domain.com/webhook-receiver>",
    "signing_key": "webhook_signing_key",  // Only provided on creation
    "last_sent_at": null,
    "last_failed_at": null,
    "failed_attempts": 0
}

```

## Updating a Webhook

Update an existing webhook configuration.

### Endpoint

```
PUT /api/v2/webhooks/:id
```

### Request Parameters

| Parameter      | Type   | Required | Description                                                                                                       |
| -------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `kind`         | string | No       | The type of webhook. Must be one of: `order`, `confirmation_document_available`, `certificate_document_available` |
| `endpoint_url` | string | No       | The URL where webhook events will be sent                                                                         |

### Example Request

```bash
curl -X PUT \\
  <https://api.squake.earth/v2/webhooks/webhook_id> \\
  -H 'Authorization: Bearer YOUR_API_TOKEN' \\
  -H 'Content-Type: application/json' \\
  -d '{
    "endpoint_url": "<https://your-domain.com/new-webhook-receiver>"
  }'

```

### Response

### Success (200 OK)

```json

    "id": "webhook_id",
    "kind": "order",
    "endpoint_url": "<https://your-domain.com/new-webhook-receiver>"
}

```

### Not Found (404)

Returned when the webhook ID doesn't exist or belongs to another client.

## Deleting a Webhook

Remove an existing webhook configuration.

### Endpoint

```
DELETE /api/v2/webhooks/:id
```

### Example Request

```bash
curl -X DELETE \\
  <https://api.squake.earth/v2/webhooks/webhook_id> \\
  -H 'Authorization: Bearer YOUR_API_TOKEN'

```

### Important Notes

1. The webhook signing key is only returned once during webhook creation. Make sure to store it securely.
2. The endpoint URL must be a valid HTTPS URL that can receive POST requests.
3. Each client can create multiple webhooks for different purposes.
4. Available webhook kinds:
   * `order`: Notifications about order-related even
   * `confirmation_document_available`: Notifications when confirmation documents become available
   * `certificate_document_available`: Notifications when certificate documents become available