Monitoring follows a RESTful-style API implementation. Core concepts used in monitoring include: GET requests for index/show, POST requests for creating a monitor, PUT requests to update a monitor, and DELETE requests to delete a monitor.
Please refer to the monitoring API documentation for additional details.
-
Notifiers: Webhook configurations that receive alerts when matches are found in the screening process. They define where and how notifications should be sent, including the destination URL and authentication settings (like secret keys). Think of notifiers as the communication channels for alerting your systems when something important is detected.
-
A single notifier can be used by multiple monitors, allowing you to centralize alert handling. Your organization can have multiple notifiers for different purposes, such as high-risk alerts versus routine screenings.
-
A client-provided webhook is required for routing notifications from Castellum to your system
-
-
Monitors: Configurations that define your screening parameters and link to a specific notifier. They establish which list you are screening for (like all sanctions or PEPs) and how strict the matching should be (via min_score thresholds). Monitors are essentially your screening rulebooks that determine when an alert should be triggered. You can think of these as saved screening queries that are applied to all names (screen entities) associated with the monitor.
-
A monitor can only have one notifier, but can contain multiple screen entities. Different monitors can use different screening parameters even while monitoring the same entities.
-
The one-to-many structure allows specialized monitoring profiles (e.g., "High-Risk Clients," "PEP Screening," "Sanctions Only") with tailored parameters, each sending alerts to a designated notification endpoint.
-
-
Screen Entities: The individuals or organizations being continuously monitored against watchlists. These are the subjects you want to keep an eye on for potential risk matches. Each entity includes identifying information such as names, dates of birth, ID numbers, and locations to improve match accuracy.
-
Screen entities belong to specific monitors. The same entity can be added to multiple monitors with different screening parameters. Each entity must have a unique provider_id within a given monitor. The reference_id is a string that allows any additional information that needs to be associated with the entity to be passed in and returned with the notification.
-
You can implement tiered monitoring by adding critical entities to multiple monitors with different sensitivity levels. Changes to entity information must be updated separately for each monitor where the entity appears.
-
-
Notifications: Alerts are generated when matches are found during the screening process. These contain information about which entities matched against which watchlists, along with relevant match details. Notifications are delivered to your systems via the configured notifiers/webhooks.
-
A notification is associated with one monitor and one notifier. A single notification can contain multiple hits for different entities associated with that monitor.
-
Your webhook should be designed to process batch alerts that may contain multiple entities and hits in a single notification payload.
-
-
Hits: Specific matches between your monitored entities and entries on watchlists. Each hit includes details about the matched watchlist entry and a match score indicating the confidence level of the match. Hits are the core risk indicators that your compliance team would review. These are the same data that the screening endpoints return.
-
Hits belong to specific screen entities. A single entity can have multiple hits across different watchlists. Each hit has a unique hit_ref identifier, which can be used to query that hit through the API, if needed.
-
-
Receipts: Records confirming that notifications were successfully delivered to your webhook endpoints. These include details about notification delivery, such as response codes and timestamps, which provide an audit trail for compliance purposes or debugging if a webhook isn't receiving notifications. We will retry sending to the webhook every hour for 24 hours.
-
Each receipt corresponds to a specific attempt to deliver a notification. Multiple receipts may exist for a single notification if retries were needed.
-