Webhooks & Callbacks

Asynchronous API Patterns

Webhooks and callbacks describe outbound HTTP calls your API makes. These patterns are essential for event-driven architectures and async workflows.

Key Differences
  • • Webhooks - Top-level events, independent of any operation (3.1+)
  • • Callbacks - Tied to a specific operation, triggered by that request

Webhooks

OpenAPI 3.1+

Define outbound API calls your service makes to external URLs. Webhooks are top-level objects, not tied to any specific endpoint.

Order Created Webhook
openapi: '3.1.0'
info:
title: E-commerce API
version: '1.0.0'
webhooks:
orderCreated:
post:
summary: New order notification
description: |
Sent when a new order is placed.
Register your URL in the merchant dashboard.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OrderEvent'
responses:
'200':
description: Webhook received
Common Webhook Events
  • • Order created / updated / cancelled
  • • Payment completed / failed
  • • User registered / verified
  • • Subscription renewed / cancelled
  • • Resource created / deleted
Webhook vs Regular Endpoint
  • Regular: Client calls your API
  • Webhook: Your API calls client's URL
  • Direction: Outbound vs inbound

Defining Multiple Webhooks

Each webhook is a named entry with its own operation(s).

webhooks:
orderCreated:
post:
summary: Order created
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/OrderEvent'
responses:
'200': { description: OK }
orderShipped:
post:
summary: Order shipped
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ShipmentEvent'
responses:
'200': { description: OK }
paymentFailed:
post:
summary: Payment failed
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentEvent'
responses:
'200': { description: OK }

Callbacks

OpenAPI 3.0+

Callbacks are outbound calls triggered by a specific operation. Unlike webhooks, they're defined inside the operation that initiates them.

Subscription Callback Example
paths:
/subscriptions:
post:
summary: Create a subscription
requestBody:
content:
application/json:
schema:
type: object
properties:
callbackUrl:
type: string
format: uri
topic:
type: string
responses:
'201':
description: Subscription created
callbacks:
onEvent:
'{$request.body#/callbackUrl}':
post:
summary: Event notification
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Event'
responses:
'200':
description: Callback acknowledged

Runtime Expressions

Dynamic

Callback URLs can include runtime expressions to dynamically construct the URL from request/response data.

ExpressionSourceExample
$urlRequest URLhttps://api.example.com/sub
$methodHTTP methodPOST
$request.path.idPath parameter123
$request.query.filterQuery parameteractive
$request.header.X-IdRequest headerabc123
$request.body#/urlRequest body fieldhttps://client.com/hook
$response.body#/idResponse body fieldsub-456
$response.header.LocationResponse header/subs/456
Expression Examples
# URL from request body
'{$request.body#/callbackUrl}'
# Include response ID in callback path
'{$request.body#/baseUrl}/events/{$response.body#/id}'
# Construct URL from parts
'https://{$request.body#/host}/webhook/{$request.path.id}'

Version Compatibility

FeatureSwagger 2.0OpenAPI 3.0OpenAPI 3.1
CallbacksNoYesYes
WebhooksNoNoYes

Conversion Note

When converting from 3.1 to 3.0, webhooks are removed (3.0 doesn't support them). Callbacks are preserved. Consider documenting webhooks separately for 3.0 compatibility.

Tigrister Support

Full

Tigrister fully supports both webhooks and callbacks with dedicated UI components.

Webhooks Section
  • • Add/edit/delete/rename webhooks
  • • Method badge display (POST, PUT, etc.)
  • • Summary inline display
  • • Count badge showing total webhooks
  • • Empty state with "Add Webhook" button
  • • Schema selection from components
Callbacks Editor
  • • Full callback operation editing
  • • Request body schema selection
  • • Content type configuration
  • • Required flag support
  • • Response definition with status codes
  • • Runtime expression URL display
Preview
  • • Webhooks displayed in API documentation
  • • Callback documentation per operation
  • • Schema visualization with expand/collapse

Best Practices

Include Event Type in Payload

Add a type or event field so receivers can route events.

Document Expected Response

Specify what response you expect (usually 200 OK) and timeout behavior.

Consider Retry Logic

Document your retry policy for failed webhook deliveries in the description.

Use Security Headers

Include signature headers (like X-Signature) so receivers can verify authenticity.

Server VariablesPreview & Try It Out