# Automatic notification of migration using webhooks integration

Source: https://dev.arcxp.com/migration-center/developer-docs/automatic-notification-of-migration-using-webhooks-integration-with-migration-center/

Migration Center is able to send notifications to customer applications when it fully migrates a document to Arc XP. The notification occurs when you register a webhook URL with Migration Center’s webhook registration service. If the webhook setting is enabled for an organization, Migration Center sends a message to the URL when an ingested document of any content type reaches one of the following statuses:

- Success
- Circulated
- Published
- Scheduled
- FailVideo
- FailImage
- FailStory
- FailGallery
- FailAuthor
- FailTag

The webhook registration service lets you create and update a webhook with Migration Center. You can create and update a webhook through HTTP calls as the following code samples illustrate.

## Creating a webhook in Migration Center

```
curl --location --request POST 'https://api.{org}.arcpublishing.com/migrations/v3/webhook' \
--header 'Authorization: Bearer <INSERT YOUR ARC BEARER TOKEN HERE' \
--header 'Content-Type: application/json' \
--data-raw '{
    "endpoint":"https://api.{{org}}.arcpublishing.com/notify/stage/bug_bush_3_3",
    "authToken":" <INSERT YOUR WEBHOOK BEARER TOKEN HEREl",
    "isEnabled":true,
    "headers":{
        "Accept-Language":"en-US"
    },
    "subscriber": "sandbox_webhook_1"
}'
```

The POST request sent to the `/migrations/v3/webhook` endpoint requires an authorization token and a `Content-type` header as is the case with any other API endpoints within Migration Center. The request payload must contain the following properties:

| **Request Body Property** | **Property Description**                                                                                                                                                                                                                                                                                                                                                    | **Required** |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| endpoint                  | The customer’s webhook API endpoint. This endpoint must support a POST operation.                                                                                                                                                                                                                                                                                           | Yes          |
| authToken                 | The authorization token to secure calls to the customer’s webhook endpoint.                                                                                                                                                                                                                                                                                                 | Yes          |
| isEnabled                 | A boolean value to start and stop notifications to the webhook API                                                                                                                                                                                                                                                                                                          | No           |
| headers                   | A dictionary of any HTTP headers that are required to passed in the request to the customer’s webhook endpoint. If no headers are required, this property can be ignored.                                                                                                                                                                                                   | No           |
| subscriber                | The name of the webhook in the case where you maintain multiple webhooks with Migration Center. Passing the subscriber name in the POST /ans or POST /ans/bulk API call links the Arc XP Native Specification (ANS) documents in the POST call to a particular webhook integration on the client side. Migration Center calls the webhook that matches the subscriber name. | Yes          |

The current max limit of webhooks per Arc XP organization is five, and Migration Center rejects any additional attempts to register more webhooks with the following error response:

```
{
    "success": false,
    "message": "Max items exceeded for entity 'Webhooks'. This entity has a limit of 5."
}
```

## Updating a webhook in Migration Center

```
curl --location --request PATCH 'https://api.{org}.arcpublishing.com/migrations/v3/webhook/1' \
    --header 'Authorization: Bearer <INSERT YOUR ARC BEARER TOKEN HERE>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
    "isEnabled":false
}'
```

You can update the webhook through a PATCH call to the webhook registration service as shown in the previous sample and passing in the ID returned in the API response to the `POST /migrations/v3/webhook` call. This process lets you update your authorization tokens when they are recycled or disable notifications from Migration Center.

## Getting a list of all webhooks in Migration Center

```
curl --location --request GET 'https://api.{org}.arcpublishing.com/migrations/v3/webhook' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer <INSERT YOUR ARC BEARER TOKEN HERE>' \
    --data-raw ''
```

Sample response:

```
{
    "hasMore": false,
    "webhooks": [
        {
            "id": 1,
            "endpoint": "https://api.{org}.arcpublishing.com/migrations/v3/mywebhookapi",
            "headers": {
                "Content-Type": "application/json"
            },
            "isEnabled": true,
            "createDate": "2022-12-08T17:33:56.990Z",
            "updateDate": "2022-12-08T17:44:20.804Z",
            "subscriber": "test"
        }
    ]
}
```

> **Note:**
>
> For security reasons, the response does not include the authorization token.

## Using the subscriber to link a `POST /ans` request to a specific webhook

In the case where your application maintains multiple webhooks with Migration Center, you can use the subscriber name to match specific migration records to webhooks. Passing the subscriber name in the `POST /ans` or `POST /ans/bulk` API call links the ANS documents in the POST call to a particular webhook integration on the client side. Migration Center calls the webhook that matches the subscriber name.

```
{
    "tags": {
        "webhookSubscriber": "sandbox_webhook_1"
    },
    "ANS": {...}
}
```

## Notification message by Migration Center to the webhook

If a webhook has been registered and its `isEnabled` setting is set to `true`, Migration Center posts a message to the webhook URL using the authorization token and HTTP headers provided during registration, when an ingested document reaches a terminal status. You can find the list of statuses at the beginning of this section. The POST message payload looks something like the following code sample and includes the `ansId`, `ansType`, and `status` of the migrated document, along with the document’s metadata.

```
"record": {
            "id": 229338,
            "sourceLocation": null,
            "sourceAdditionalProperties": null,
            "ansId": "T3GBOT63EBA4JGFU4RPTCQPK4Q",
            "ansType": "author",
            "ansLocation": "{org}/stage/author/7fc2b6cb-badb-438a-8d13-8ec8d9fde628/ans.json",
            "status": "Circulated",
            "website": null,
            "operations": null,
            "circulationLocation": "{org}/stage/author/7fc2b6cb-badb-438a-8d13-8ec8d9fde628/circulations.json",
            "createDate": "2022-12-07T19:49:00.157Z",
            "updateDate": "2022-12-07T19:49:00.157Z",
            "errorMessage": null,
            "priority": "historical",
            "arcAdditionalProperties": null,
            "groupId": null
}
```
