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.

How to register a web hook can be found at Create a new subscription. Once your API endpoint is registered, it will be called (verb POST) for the events you registered for. In the response body of declaration-related events, the URL of the declaration is provided. This allows you to easily retrieve the full details of the declaration from the declaration API when needed. The exact content of the body depends on the event type, which can be found below.

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, UK specific documents)
  • 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.

Retry policy

Events are sent to the registered webhook of each subscription immediately. 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.

Message delivery status

CAS uses HTTP response codes to acknowledge the receipt of events by webhooks.

Success codes

The following HTTP response codes indicate that an event has been delivered successfully to your webhook. CAS considers delivery complete for these response codes.

  • 200 OK
  • 201 Created
  • 202 Accepted
  • 204 No Content

Failure codes

The following HTTP response codes indicate that an event delivery attempt failed, and CAS will retry delivery as described under the retry policy.

  • 400 Bad Request
  • 401 Unauthorized
  • 404 Not Found
  • 408 Request timeout
  • 414 URI Too Long
  • 500 Internal Server Error
  • 503 Service Unavailable
  • 504 Gateway Timeout