# Webhooks

The **Webhooks** tab under **Settings** manages the endpoints Borkol notifies when things happen in your store. Webhooks push order and stock events to your storefront or integration as they happen, so you don't have to poll the API. Borkol POSTs signed JSON to each endpoint for the events it subscribes to.

This page covers the dashboard side; the payload formats, signature details, and retry behavior live in the [Webhooks API reference](/api/webhooks/index).

## Add an endpoint

1. Open **Settings** and switch to the **Webhooks** tab.
2. In the **Add endpoint** card, enter the **Endpoint URL** your server listens on (for example `https://example.com/webhooks/borkol`).
3. Check at least one event. The **Create** button stays disabled until you have both a URL and an event; a hint next to it tells you which is missing.
4. Click **Create**.

### Events

There are three events to choose from:

| Event | Sent when |
| --- | --- |
| `order.created` | A new order is placed. |
| `order.status_changed` | An order moves to a different status. |
| `stock.adjusted` | A stock level changes. |

## Copy the signing secret — it is shown once

Right after creation, the endpoint's signing secret appears in a card titled **Copy this signing secret now. Shown once.** Store it on your server immediately:

- Your server verifies each delivery by comparing the `X-Borkol-Signature` header to an HMAC-SHA256 of the raw request body computed with this secret. Reject deliveries that do not match.
- The secret can never be viewed again after you leave the page. If you lose it, delete the endpoint and add it again to get a new secret.

## Turn an endpoint on or off

Each endpoint card has an **Active** / **Inactive** switch. Flip it off to pause deliveries without deleting the endpoint, and back on to resume. The switch updates immediately; if saving fails, it flips back and shows an error.

## Send a test ping

Click **Test** on an endpoint to send it a ping delivery. You see **Ping sent.** as confirmation. Use this to check your server receives and verifies deliveries before real events flow.

## Check the delivery log

Click **Deliveries** on an endpoint to expand its delivery log inline (click **Hide deliveries** to collapse it). Each row shows:

| Column | Description |
| --- | --- |
| Status | Delivery status badge (see below). |
| Event | The event that was delivered. |
| Response | The HTTP status your server returned, or a dash if there was no response. |
| Attempts | How many delivery attempts have been made. |
| Date | When the delivery happened, with time. |

| Status | Meaning |
| --- | --- |
| `pending` | Queued or still being retried. |
| `success` | Your server accepted the delivery. |
| `failed` | Delivery gave up after exhausting its attempts. |

An endpoint that has never received anything shows **No deliveries yet.**

## Delete an endpoint

1. Click **Delete** on the endpoint's card.
2. A **Delete endpoint** dialog confirms: the endpoint stops receiving events immediately.
3. Click **Delete** to confirm.

Deleting also discards the endpoint's signing secret. If you only want to pause deliveries, use the **Active** switch instead.