> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blips.network/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> The current webhook documentation boundary and how it should move into OpenAPI 3.1 over time.

# Webhooks

The current public OpenAPI file includes a webhook connectivity helper endpoint, but it does not yet include the business callback contracts themselves.

This page should be treated as callback documentation, not as a Try it endpoint page.

## What exists today

* `POST /webhooks/test` is the support/helper verification endpoint.
* `POST /webhooks/test` can be documented directly from the OpenAPI `paths` section.
* Callback-only webhook payloads are intentionally excluded from the current public reference file.

## What should happen next

The long-term target is:

1. keep the verification helper endpoint in the generated API Reference
2. define callback contracts in the OpenAPI 3.1 `webhooks` section
3. attach dedicated MDX pages to those webhook definitions for delivery policy, retries, signatures, and operator guidance

## Why this split matters

Verification helpers and callback contracts are not the same thing.

The helper endpoint is a client-invoked API call.
The callback contract is an event delivered by BLIPS to the integrator.

The callback should be acknowledged with transport-level `200 OK`.

Business decisions for incoming transaction review do not happen by replying to the webhook itself. They happen through the transaction action endpoints:

* `POST /transactions/{transactionId}/approve`
* `POST /transactions/{transactionId}/reject`

Treating them separately keeps the public docs cleaner and makes Mintlify's generated webhook support more useful once the canonical spec includes `webhooks`.

So the intended public shape is:

* generated API page for the webhook verification helper
* MDX callback docs for webhook delivery contracts
* no attempt to present callback contracts as ordinary interactive Try it pages