Outbound webhooks
The endpoints this store posts events to, and the delivery log for them.
Outbound webhooks are what this store sends. Each subscription names a URL and the events it wants, and every attempt is logged. The incoming half, what a payment provider posts to the store, is the webhook log.
List outbound webhook subscriptions
/api/v1/kahunacart/webhook-subscriptions
Every outbound webhook subscription — a topic and a URL another system is told about — with its status (active, paused, disabled), failure streak and last delivered and failed times, plus the counts per status, every topic a subscription may name, the disable threshold and the delivery-log retention. The signing secret is never in the answer: it is shown once on creation and on rotation and cannot be read back.
Create an outbound webhook subscription
/api/v1/kahunacart/webhook-subscriptions
Create a subscription and answer with its signing secret, once. The topic is a named topic such as order.paid, an event name such as event.onKahunaCartOrderPaid, or a family such as order.*; an unknown topic is refused with the nearest matches. The target must be https except on a development host. A subscription starts paused; ping: true pings the target and activates it on a 2xx.
Parameters
| Name | Type | Description |
|---|---|---|
| name required | string | What the merchant calls it |
| topic required | string | A named topic, an event.<name>, or a family such as order.* |
| target_url required | string | Where to POST; https except on localhost and .test hosts |
| ping optional | boolean | Ping now and activate on a 2xx |
Update an outbound webhook subscription
/api/v1/kahunacart/webhook-subscriptions/{id}
Rename, retarget or change the topic; pause; activate, which pings the target first and refuses with the reason when the ping fails; or rotate the secret, which answers with the new one once and stops the old one working at that moment.
Parameters
| Name | Type | Description |
|---|---|---|
| id required | integer | Subscription id |
| name optional | string | |
| topic optional | string | |
| target_url optional | string | |
| status optional | string |
active pings first
One of:
active, paused |
| rotate_secret optional | boolean | Mint a new secret; the answer carries it once |
Delete an outbound webhook subscription
/api/v1/kahunacart/webhook-subscriptions/{id}
Delete a subscription. Its delivery rows stay until retention sweeps them, so what it delivered can still be read.
Parameters
| Name | Type | Description |
|---|---|---|
| id required | integer | Subscription id |
List outbound webhook deliveries
/api/v1/kahunacart/webhook-deliveries
The outbound delivery log, one row per attempt, newest first: the subscription, the topic, the event id, the order it concerned, the attempt number, the response status, a 2 KB excerpt of the response, how long it took and any error. Filter by subscription_id, order_id or event_id. Each row says whether it can be redelivered.
Parameters
| Name | Type | Description |
|---|---|---|
| subscription_id optional | integer | |
| order_id optional | integer | |
| event_id optional | string | |
| sort optional | string |
A column to sort the whole list by before it is paged; leave out for the usual order
One of:
id, subscription, topic, order, result, took, when |
| dir optional | string |
One of:
asc, descDefault:
asc |
| q optional | string | Words to search for in the subscription name, the topic, the order number and the error; every word has to be there, in any order. Applied before the sort and the page, and total counts what it found |
| page optional | integer | |
| per_page optional | integer |
Redeliver an outbound webhook
/api/v1/kahunacart/webhook-deliveries/{id}/redeliver
Queue one attempt's occurrence again, to that one subscription, with the same event id so the receiver can deduplicate. A new row appears in the log when the worker sends it. 409 when the occurrence has been swept from the queue, or the row is a ping.
Parameters
| Name | Type | Description |
|---|---|---|
| id required | integer | Delivery row id |
Ping a webhook subscription
/api/v1/kahunacart/webhook-subscriptions/{id}/ping
Send a ping delivery and report the answer. Part of update_webhook_subscription's activate for a model; the admin's Ping button for a person
A delivery that failed can be sent again with redeliver; the original attempt stays in the log. ping sends a ping delivery to a subscription and reports what came back, which is how a merchant tests an endpoint before switching it on.