CAS allows you to register one of your own API endpoints as a webhook to be called in case an event is triggered like a status change of a declaration, a document is created or an alert. The configured API endpoint will be invoked with an HTTP POST request when an event occurs the subscription is registered to. The body of this request will contain details of the event, which structure can be found at Notification events. For example declaration-related notifications will also include the id and url of a declaration which can in turn be used to retrieve more details of the affected declaration.

Events for which notifications can be sent are

• Status changes across entire declaration lifecycle (possible to subscribe to specific status changes)
• A document has been generated (SAD, EAD, COO, T2L, ...)
• Ingestion failed
• (un)successful replace of customs shipment
• Customs duties received
• Transit guarantee threshold reached

Event Types and Subtypes

There are several events in CAS that can send out a notification. To distinguish between these different cases, we use Event Types and Event Subtypes. When you receive a notification event the type and subtype will be provided. When creating a subscription, you can filter the notifications you want to receive specifying the Type and Subtype. A list of Event Types and Subtypes, with their message structure, can be found at Notification events.

Error handling

Events are sent to the registered webhook of each subscription immediately. CAS uses HTTP response codes to acknowledge the receipt of events by webhooks.

Any response code in the success range (2xx) will be considered a successful delivery. If a webhook does not successfully acknowledge the receipt of an event, CAS Notifications retries delivery of the event following an exponential backoff strategy schedule:

1. 10 seconds
2. 30 seconds
3. 1 minute
4. 5 minutes
5. 10 minutes
6. 30 minutes
7. 1 hour
8. 3 hours
9. 6 hours
10. Every 12 hours up to 24 hours

CAS adds a small randomization to all retry intervals and may opportunistically skip certain retries, if an endpoint is consistently unhealthy, down for a long period, or appears to be overwhelmed. CAS expires all events that are not delivered within 24 hours.

Setting up a subscription

Notifications will only be sent from the moment a matching subscription is created. When creating a subscription later, CAS won't send a request for any event that happened before this moment.

Setting up a new subscription requires you to take the following steps:

1. Make sure your system has an endpoint that can process HTTP POST requests with a body matching the needed schema (as per Notification events), which is accessible publically over the internet. Collect the url for this endpoint for the destinationUrl field in step 3.
2. (Optional) If you want to protect your endpoint using the OAuth2.0 client-credentials flow, make sure to set up an OAuth2.0 application in your identity platform that will be used by CAS to obtain access tokens which have access to the above endpoint. Once this is done, gather the following values for step 3:
   1. Url for the token endpoint (for the accessTokenUrl field in step 3)
   2. ClientId
   3. ClientSecret
   4. (Optional) Audience
   5. (Optional) Scope
3. Use the Create a new subscription endpoint to subscribe your endpoint to the needed event (sub)type(s).

Currently one subscription can be linked to one eventType only (either without filtering for specific subTypes, or with filtering on one specific subType). This may change in the future so a single subscription can be linked to multiple types, without having to create separate subscriptions for this. Once created, a subscription can't be updated. Alternatively, create a new subscription and delete the old one once the new subscription is receiving data successfully.