Webhook and Callback Extensions

OpenAPI 3.x describes the requests your API sends to clients as webhooks (the root webhooks object) and callbacks (an operation's callbacks). The x-webhooks and x-callbacks extensions, at the root of your definition, add what a client needs to handle these requests:

• Groups of related webhooks or callbacks.
• A discriminator that tells which webhook or callback an incoming request is.
• Signature verification that tells how to check that a request came from your API.

x-webhooks and x-callbacks work the same way. Each takes one of two shapes: a single group written directly under the extension, or several named groups. You can't mix the two shapes in one extension.

For which SDK languages support webhooks and callbacks, see Languages & Features.

Use a single groupCopy Anchor Link

When all your webhooks share the same discriminator and signature, put description, discriminator, and signatureVerification directly under the extension. APIMatic imports them as one group named default, and every webhook or callback without a group belongs to it.

x-webhooks:
  description: Payment status events
  discriminator:
    propertyPointer: $request.body#/event_type
    mapping:
      payment.created: paymentCreated
      payment.updated: paymentUpdated
  signatureVerification:
    signatureHeader: X-Webhook-Signature
    timestampHeader: X-Webhook-Timestamp
    replayTolerance: 300
    signatureTemplate: "t={$request.header.X-Webhook-Timestamp},sha256=hex(hmacSha256({$request.header.X-Webhook-Timestamp}.{$request.body}))"

webhooks:
  paymentCreated:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PaymentEvent"
  paymentUpdated:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PaymentEvent"

In this shape, the discriminator's propertyPointer can point to a top-level property of the request body, such as $request.body#/event_type, or to a request header, such as $request.header.X-Event-Type.

Signature verificationCopy Anchor Link

The signatureTemplate contains at least one digest block of the form encoding(algorithm(message)):

• encoding is hex, base64, or base64url.
• algorithm is hmacSha256 or hmacSha512.
• message is the signed content. It can't be empty.

The message and the text around the digest block can contain the placeholders {$request.body} (the raw request body) and {$request.header.Name} (the value of request header Name). Placeholders inside the digest block are signed; text and placeholders outside it are only part of the header's format.

Use named groupsCopy Anchor Link

When your webhooks or callbacks need different discriminators or signatures, define several groups. Each key under the extension is a group name.

x-webhooks:
  rides:
    description: Ride lifecycle events
    discriminator:
      propertyPointer: $request.body#/event_type
      mapping:
        ride.status.updated: rideStatusUpdated
        driver.assigned: driverAssigned
    payloadVerification:
      signatureHeader: X-Signature
      algorithm: HMAC-SHA256
      digestEncoding: hex
      messageTemplate: "{$request.body}"
      signatureValueTemplate: "sha256={digest}"

Because description, discriminator, signatureVerification, and payloadVerification mark the single-group shape, you can't use them as group names. A named group uses payloadVerification, not signatureVerification.

Payload verificationCopy Anchor Link

messageTemplate can contain these placeholders, separated by exactly one character, such as a period:

Assign webhooks and callbacks to a groupCopy Anchor Link

With named groups, assign each webhook or callback to its group by setting x-webhook-group or x-callback-group in its Operation Object. The value must be the name of a group in x-webhooks or x-callbacks.

webhooks:
  rideStatusUpdated:
    post:
      x-webhook-group: rides
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RideStatusEvent"

paths:
  /rides:
    post:
      callbacks:
        rideStatusUpdatedCallback:
          "{$request.body#/callback_url}":
            post:
              x-callback-group: rideUpdates
              requestBody:
                content:
                  application/json:
                    schema:
                      $ref: "#/components/schemas/RideStatusEvent"

With a single group, you don't need these extensions: webhooks and callbacks without one belong to the default group.

DiscriminatorCopy Anchor Link

The discriminator tells which webhook or callback an incoming request is.

ValidationCopy Anchor Link

The rules for these extensions are in the OpenAPI Webhooks, OpenAPI Callbacks, and OpenAPI Webhook and Callback Signature Verification sections of OpenAPI v3 APIMatic Linting, and in the Webhooks section of APIMatic CodeGen Validation.