Callbacks

In OpenAPI 3 specs, you can define callbacks – asynchronous, out-of-band requests that your service will send to some other service in response to certain events. This helps you improve the workflow your API offers to clients. A typical example of a callback is subscription functionality – users subscribe to certain events of your service and receive a notification when this or that event occurs. For example, an e-shop can send a notification to the manager on each purchase. These notifications will be “out-of-band”, that is, they will go through a connection other than the connection through which a visitor works, and they will be asynchronous, as they will be out of the regular request-response flow. In OpenAPI 3, you can define the format of the “subscription” operation as well as the format of callback messages and expected responses to these messages. This description will simplify communication between different servers and will help you standardize the use of webhooks in your API.

Callback Example

Let’s create a callback definition – a simple webhook notification. Suppose, your API provides a POST /subscribe operation that expects a callback URL in the request body:

1
POST /subscribe
2
Host: my.example.com
3
Content-Type: application/json
4

5
{
6
  "callbackUrl": "https://myserver.com/send/callback/here"
7
}

The API acknowledges the subscription —

1
HTTP/1.1 201 Created

— and later sends notifications on certain events:

1
POST /send/callback/here
2
Host: myserver.com
3
Content-Type: application/json
4

5
{
6
  "message": "Something happened"
7
}

Let’s now define the /subscribe operation:

1
openapi: 3.0.4
2
info:
3
  version: 0.0.0
4
  title: test
5

6
paths:
7
  /subscribe:
8
    post:
9
      summary: Subscribe to a webhook
10
      requestBody:
11
        required: true
12
        content:
13
          application/json:
14
            schema:
15
              type: object
16
              properties:
17
                callbackUrl: # Callback URL
18
                  type: string
19
                  format: uri
20
                  example: https://myserver.com/send/callback/here
21
              required:
22
                - callbackUrl
23
      responses:
24
        "201":
25
          description: Webhook created

Now let’s add the callbacks keyword to this operation to define a callback:

1
paths:
2
  /subscribe:
3
    post:
4
      summary: Subscribe to a webhook
5
      requestBody: …
6
      callbacks: # Callback definition
7
        myEvent: # Event name
8
          "{$request.body#/callbackUrl}": # The callback URL,
9
            # Refers to the passed URL
10
            post:
11
              requestBody: # Contents of the callback message
12
                required: true
13
                content:
14
                  application/json:
15
                    schema:
16
                      type: object
17
                      properties:
18
                        message:
19
                          type: string
20
                          example: Some event happened
21
                      required:
22
                        - message
23
              responses: # Expected responses to the callback message
24
                "200":
25
                  description: Your server returns this code if it accepts the callback

Let’s walk through this definition line by line:

callbacks are defined inside the related operation - post, put, and so on (not under the path itself). In this example, under the post method of the /subscribe path:

1
paths:
2
  /subscribe:
3
    post:
4
      …
5
      callbacks:
6
        …

This does not mean that the API will send callbacks only when this operation is working. Your API will send callback requests when the business logic of your service requires. The hierarchy of keywords simply lets you use parameters of the /subscribe operation to configure the callback requests (see below).

Inside callbacks, we define one or more callback messages. In our example, we have one message only. You can find an example with multiple callbacks below. The definition of each callback starts with the event name (_myEvent_ in our example):

1
callbacks:
2
  myEvent: # Event name

Under the event name, we define the URL your service will send callback messages to. In our example, the URL is specified by using the {$request.body#/callbackUrl} expression:

1
callbacks:
2
  myEvent:
3
    "{$request.body#/callbackUrl}": # The callback URL, refers to the URL passed in the request body

This expression tells that the callback URL will be based on the parameters of the /subscribe operation. We will tell more about these expressions a bit later.

Below the URL, we specify the method of the callback message, and define the message format and the expected responses. These definitions are similar to regular request and response definitions:

1
callbacks:
2
  myEvent:
3
    "{$request.body#/callbackUrl}":
4
      post: # Method
5
        requestBody: # Contents of the callback message
6
          …
7
        responses: # Expected responses
8
          …

Please note that when you define a callback, you define a specification of your API. The actual implementation of the callback functionality is done in the server code.

Use Runtime Expressions to Refer to Request Fields

As you can see, we use the {$request.body#/callbackUrl} expression in our example. It is a runtime expression that sets which data of the POST /subscribe request will be used in callbacks. Runtime means that unlike API endpoints, this URL is not known beforehand and is evaluated at run time based on the data supplied by API clients. This value varies from one client to another. For example, the POST /subscribe request can look as follows:

1
POST /subscribe?p1=query-param-value HTTP/1.1
2
Host: my.example.com
3
Content-Type: application/json
4
Content-Length: 187
5

6
{
7
  "callbackUrl" : "http://my.client.com/callback"
8
}
9

10
201 Created
11
Location: http://my.example.com?id=123

You can use the following expressions to refer to its data:

Expression	Example	Description
`{$url}`	`/subscribe`	The parent operation URL.
`{$method}`	`POST`	The method of the callback request.
`{$request.path.eventType}`	`myEvent`	The event name.
`{$request.query.param-name}`	`query-param-value` (the `p1` query parameter)	The value of the specified query parameter.
`{$request.header.header-name}`	`application/json` (the Content-Type header)	The specified header of the “subscription” request.
`{$request.body#/field-name}`	`callbackUrl`	A field in the request body. If the field is an array, use the syntax like `{$request.body#/arrayField/2}`.
`{$response.header.header-name}`	`http://my.example.com?id=123` (the Location header)	The value of the specified response header (the response to the “subscription” request).

You can combine a runtime expression with static data in callback definitions. For instance, you can define the callback URL in the following way:

1
{$request.body#callbackUrl}/data:
2
– or –
3
{$request.body#/callbackUrl}/{$request.query.eventType}:

You can use expressions to specify query parameters:

1
{$request.body#/callbackUrl}/data?p1={$request.query.eventType}

If the string includes both runtime expressions and static text, you should enclose the runtime expressions in curly braces. If the whole string is a runtime expression, you can skip the curly braces.

Multiple Callbacks

As we have said above, you can use one “subscription” operation to define multiple callbacks:

1
/subscribe:
2
  post:
3
    requestBody:
4
      content:
5
        application/json:
6
          schema:
7
            type: object
8
            properties:
9
              inProgressUrl:
10
                type: string
11
              failedUrl:
12
                type: string
13
              successUrl:
14
                type: string
15
    responses:
16
      "200":
17
        description: OK
18
    callbacks:
19
      inProgress:
20
        "{$request.body#/inProgressUrl}":
21
          post:
22
            requestBody:
23
              $ref: "#/components/requestBodies/callbackMessage1"
24
            responses:
25
              "200":
26
                description: OK
27
        "{$request.body#/failedUrl}":
28
          post:
29
            requestBody:
30
              $ref: "#/components/requestBodies/callbackMessage2"
31
            responses:
32
              "200":
33
                description: OK
34
        "{$request.body#/successUrl}":
35
          post:
36
            requestBody:
37
              $ref: "#/components/requestBodies/callbackMessage3"
38
            responses:
39
              "200":
40
                description: OK

Unsubscribing From Callbacks

The way you implement the unsubscription mechanism is up to you. For example, the receiving server can return specific code in response to the callback message to indicate that it is no longer interested in callbacks. In this case, clients can unsubscribe only in response to a callback request. To allow clients to unsubscribe at any time, your API can provide a special “unsubscribe” operation. This is a rather common approach. In this case, your service can generate an ID or token for each subscriber and return this ID or token in a response to the “subscription” request. To unsubscribe, a client can pass this ID to the “unsubscribe” operation to specify the subscriber to be removed. The following example demonstrates how you can define this behavior in your spec:

1
paths:
2
/subscribe:
3
  description: Add a subscriber
4
  post:
5
    parameters:
6
      - name: callbackUrl
7
        in: query
8
        required: true
9
        schema:
10
          type: string
11
          format: uri
12
      - name: event
13
        in: query
14
        required: true
15
        schema:
16
          type: string
17
    responses:
18
      '201':
19
        description: Added
20
        content:
21
          application/json:
22
            type: object
23
            properties:
24
              subscriberId:
25
                type: string
26
                example: AAA-123-BBB-456
27
    links:  # Link the returned id with the unsubscribe operation
28
      unsubscribeOp:
29
        operationId: unsubscribeOperation
30
            parameters:
31
              Id: $response.body#/subscriberId
32
    callbacks:
33
      myEvent:
34
        '{$request.query.callbackUrl}?event={$request.query.event}':
35
          post:
36
            requestBody:
37
              content:
38
                application/json:
39
                  example:
40
                    message: Some event
41
            responses:
42
              '200':
43
                description: OK
44

45
/unsubscribe:
46
  post:
47
    operationId: unsubscribeOperation
48
    parameters:
49
      - name: Id
50
        in: query
51
        required: true
52
        schema:
53
          type: string

Did not find what you were looking for? Ask the community
Found a mistake? Let us know