Automatic notification of migration using webhooks integration

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

• FallStory

• 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 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
}