Skip to main content

​
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