Webhooks

A webhook endpoint is a URL of yours that ai.ml calls when something happens in your organization: a top-up is booked, a budget runs out, a key is about to expire, an invoice is issued. The Webhooks screen manages those endpoints.

Owners and admins can create and change endpoints. Members and viewers can see the endpoints and their delivery logs, but the buttons are disabled for them.

Create an endpoint

1. Press New endpoint.
2. Enter the URL. It must start with https:// and must be reachable from the public internet; private addresses are refused.
3. Optionally add a Description, to tell endpoints apart in the list.
4. Under Events, choose what the endpoint receives. See the next section.
5. Press Create endpoint.

The endpoint appears in the list as active, and its secret is shown at the top of the screen.

Choose events

The Events list shows every event with a short description of when it is sent. Tick the ones you want, or tick all events to receive everything, including events added later. A new endpoint starts with topup.completed, topup.failed and budget.exhausted ticked. You must choose at least one.

To change the events later, open the endpoint, press Edit events, change the ticks and press Save events.

The payload of each event is described in the webhooks reference.

The secret is shown once

Each endpoint has a secret, used to sign every delivery. It is displayed only once, right after you create the endpoint or rotate its secret.

1. Press Copy and store the secret where your receiving code can read it.
2. Tick I have stored it.
3. Press Done.

After that the console shows only a hint of the secret under the endpoint's URL. If you lose the secret, rotate it.

Rotate the secret

Open the endpoint and press Rotate secret. A new secret is shown once, the same way. The old secret stops verifying immediately, so update your receiver straight away.

Send a test

Open the endpoint and press Send test. A test event is queued, and it appears in the delivery log below within moments. Use it to check that your endpoint is reachable and that your signature check passes before real events arrive.

Read the delivery log

Click an endpoint's URL, or Deliveries on its row, to open it. The log lists every delivery to that endpoint, newest first:

On each row:

• payload shows the exact body that was sent and, for a delivery that did not succeed, the last error.
• redeliver sends that event again. It needs the owner or admin role.

Older deliveries loads earlier ones.

A delivery counts as delivered when your endpoint answers with a success status. One that fails is retried with an increasing wait, from 30 seconds up to 6 hours, for 10 attempts in all, and is then marked failed. Answer quickly and do slow work afterwards, so that a delivery is not retried because your handler was still busy.

The endpoint list also shows, for each endpoint, its events, its status and the time of its Last delivery.

A failing or disabled endpoint

The Status column shows one of:

• active: deliveries are succeeding.
• failing: deliveries have been failing since the time shown. They are still being retried.
• disabled: nothing is sent.

An endpoint that fails for 72 hours is disabled automatically. The list then reads "auto-disabled after 72 h of failures", and a notice is sent to your organization's billing e-mail address, since the endpoint itself cannot carry the news.

To bring it back:

1. Fix the receiver.
2. Open the endpoint and press Re-enable.
3. Events that were missed while it was down are not sent again by themselves. In the delivery log, press redeliver on each one you need.

You can also switch an endpoint off yourself with Disable, and on again with Re-enable.

Delete an endpoint

Open the endpoint, press Delete, type delete in the confirmation and press Delete endpoint. The endpoint and its delivery log are removed.

Verify the signature

Anyone who learns your URL can post to it, so check every delivery before you trust it.

Each delivery carries a header named aiml-signature. Its value has two parts separated by a comma: t, the time the delivery was signed as a Unix timestamp in seconds, and v1, the signature.

To verify a delivery:

1. Read the request body exactly as it arrived, as raw bytes, before any JSON parsing. A body that has been parsed and written out again will not match.
2. Take the t value from the header, then a full stop, then the raw body, and join the three into one string.
3. Compute the HMAC-SHA256 of that string, using the endpoint's secret as the key, and write the result in hexadecimal.
4. Compare your result with the v1 value, using a constant-time comparison. If they differ, reject the request.
5. Compare t with the current time. If it is more than 5 minutes old, reject the request, even when the signature matches. This stops a captured delivery from being replayed later.

The same event can reach you more than once, after a retry or a redelivery. Each event has an id, shown in the payload view; keep the ids you have handled and ignore repeats.