borkoldocs

Workspace

Webhooks

Add webhook endpoints, pick events, verify signed deliveries, and monitor the delivery log.

View as Markdown

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.

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:

EventSent when
order.createdA new order is placed.
order.status_changedAn order moves to a different status.
stock.adjustedA 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:

ColumnDescription
StatusDelivery status badge (see below).
EventThe event that was delivered.
ResponseThe HTTP status your server returned, or a dash if there was no response.
AttemptsHow many delivery attempts have been made.
DateWhen the delivery happened, with time.
StatusMeaning
pendingQueued or still being retried.
successYour server accepted the delivery.
failedDelivery 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.