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 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.

Managing subscriptions

The following endpoints are available for managing notification subscriptions:

Create subscription example

Below is an example of creating a subscription for DeclarationStatusChanged events with the Released subtype, using OAuth 2.0 to protect your webhook endpoint:

{
    "eventType": "DeclarationStatusChanged",
    "eventSubType": "Released",
    "subscriptionDestination": {
        "destinationType": "OAuthApiDestination",
        "destinationDescription": {
            "destinationUrl": "https://your-system.example.com/webhooks/cas",
            "accessTokenUrl": "https://your-idp.example.com/oauth2/token",
            "clientId": "your-client-id",
            "clientSecret": "your-client-secret",
            "scope": "your-webhook-scope",
            "audience": "https://your-system.example.com"
        }
    }
}

To subscribe to all subtypes of an event type, omit the eventSubType field.

Subscription without OAuth

If your endpoint does not require OAuth authentication, omit the accessTokenUrl, clientId, clientSecret, scope, and audience fields. You can optionally include custom HTTP headers that will be sent with every notification:

{
    "eventType": "DeclarationPdfCreated",
    "subscriptionDestination": {
        "destinationType": "OAuthApiDestination",
        "destinationDescription": {
            "destinationUrl": "https://your-system.example.com/webhooks/cas",
            "additionalHeaders": [
                {
                    "name": "X-API-Key",
                    "value": "your-api-key"
                }
            ]
        }
    }
}

Create subscription response

On successful creation, the endpoint returns 201 Created with the subscription details including the assigned id:

{
    "id": "subscription-uuid",
    "eventType": "DeclarationStatusChanged",
    "eventSubType": "Released",
    "subscriptionDestination": {
        "destinationType": "OAuthApiDestination"
    }
}

Securing your webhook endpoint

When CAS sends notifications to your endpoint, you should verify that the requests genuinely originate from CAS. There are two recommended approaches:

OAuth protection (recommended): Configure OAuth credentials on your subscription (see the example above). CAS will obtain an access token from your identity provider before each call. Your endpoint validates this token as it would any other OAuth-protected request. This is the strongest verification method.

API key protection: Use the additionalHeaders feature to include a shared secret header. Your endpoint checks for this header value on every incoming request. This is simpler to implement but less secure than OAuth.