# Callback

Callback or Webhooks are another way of handling long running tasks (LRTs). Callbacks are based on the subscription principle, whereas the API notifies the API Consumer in a different connection. This pattern is also applicable to the subscription to any kind of events to get notifications from your API.

The roles are:

* API Consumer / Subscriber
* API Producer / Publisher

If the chosen way is based on using callbacks, the response to such an asynchronous operation **MUST** return, in the case of success, the **202 Accepted** status code together with an `application/hal+json` representation of a new **task-tracking resource**.

> This pattern is described by [OAS v3.0.x](https://swagger.io/docs/specification/callbacks/).

## Subscription

The subscriber enrolls to specfic notifications. The subscriber resource **MUST** provide the information about the callback URL. Any data needed to require the execution of a task **MUST** be included in the request body.

The subscription is created by using the HTTP POST Request Method. It **SHOULD** be designed as follows:

1. Subscription is accepted

   Return **201 Created** and representation of the current status. Content type: `application/hal+json` The publisher resource **MUST** provide a UUID to identify the subscription.
2. Subscription is not accepted

   Return **403 Forbidden** . Content type: `application/problem+json` with the problem detail information.

## Notification

The publisher resource **MUST** use callback URL provided by the subscriber. Any data with the output of the requested task **SHOULD** be sent to the subscriber in this request.

The callback request has to use the HTTP POST Request Method **SHOULD** as follows:

1. The subscriber accepts the callback. Content type: `application/hal+json`

   Return **200 OK**.
2. The subscriber does not accept the callback

   Return **403 Forbidden** . Content type: `application/problem+json` with the problem detail information.

## Cancel Subscription

The subscriber resource **MUST** include the UUID to identify the subscription.

It has to be used the HTTP PUT Request Method **SHOULD** as follows:

1. Subscription is accepted

   Return **202 Accepted**. Content type: `application/hal+json`
2. Subscription is not accepted

   Return **403 Forbidden** . Content type: `application/problem+json` with the problem detail information.

## Design Note

* The subscription pattern supports two main approaches:
  * On one side, it can be **only-once**. The callback will be invoked only once by the publisher and it will be cancelled automatically after.
  * On the other side, it can be **continuous**. In this case the subscription **MUST** be explicitly cancelled. Regarding the subscriber, its API is also the subject of the adidas API guidelines.
* The callback can be based on an Asynchronous/Streaming API topic. In this case the subscription is made as mentioned above but with the following differences in the workflow:
  * The API Consumer does not send a callback URL in the initial request.
  * The API Producer **SHOULD** provide the name of the topic and the UID of the task to correlate the input. 
  * It is up to the API Consumer to subscribe to the Asynchronous/Streaming API topic to receive the input from the provider. Please read the Asynchronous/Streaming API section.

### Example

1. **Settle the subscription**

   ```
    POST /items/tasks/ HTTP/1.1
    Content-Type: application/json

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

    ...

    HTTP/1.1 201 Created
    Content-Type: application/hal+json

    {
      "_links": {
        "self": { "href": "/items/tasks/4746" }
      },
      "message": "Your request to subscribe to the progress of the task has been accepted.",
      "UUID": "4746"
    }
   ```
2. **The Publisher sends the callback**

   ```
    POST https://myserver.com/send/callback/here HTTP/1.1

    {
      "_links": {
        "self": { "href": "/items/tasks/4746" }
      },
      "UUID": "4746",
      {
        <Data with the callback>
      }
    }

    ...

    HTTP/1.1 200 Ok
    Content-Type: application/hal+json
   ```
3. **Eventually the subscriber cancels the subscription**

   ```
    PUT /feeds/tasks/1 HTTP/1.1
    ...

    HTTP/1.1 202 Accepted
    Content-Type: application/hal+json

    {
      "_links": {
        "self": { "href": "/feeds/tasks/4746" }
      },
      "message": "Your subscription is cancelled."
    }
   ```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://adidas.gitbook.io/api-guidelines/rest-api-guidelines/execution/long-running-tasks/callback.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.