Watchlist Webhooks

Watchlist webhook use cases

The two primary use cases for Watchlist webhook notifications include:

Watchlist webhook configuration

Configure webhooks to receive real-time alerts from Socure for Watchlist Monitoring and Watchlist Case Management events.

You can choose to receive event notifications in one of two ways:

1. Via an HTTPS POST request to a webhook endpoint at a URL you specify.
2. Via email to a designated address.

To enable watchlist webhooks:

1. Build a webhook endpoint.
2. Register the endpoint in RiskOS™.
3. (for Monitoring) Enable monitoring on one or more evaluations

1. Build a webhook endpoint

A webhook endpoint is a public HTTPS URL that receives POST requests from Socure when an event occurs.

Requirements

At a minimum, your webhook endpoint must:

• Accept POST requests with a Content-Type: application/json.
• Respond with a 200 OK status code to acknowledge receipt. All status codes outside of this range will result in a redelivery attempt.

Idempotency

Webhook events may be delivered more than once. To prevent duplicate processing, ensure your endpoint is idempotent by tracking each event using its unique identifier:

• monitored_search_updated: use the event_id field
• case-closure: use the eventReferenceId field

Retry logic

Events must be acknowledged (with a 200 OK status code) within 30 seconds, or delivery is aborted and retried with linear backoff. After 5 failures, the webhook is deleted.

When your server receives a webhook, it must acknowledge it within 30 seconds (by returning an HTTP 200 response). If your server does not respond in time or returns a non-200 status, the delivery is treated as failed.

The system will retry delivery up to 5 times using an increasing delay (linear backoff) between each attempt. After the 5th failed attempt, the webhook is marked as failed and deleted - no more automatic retries occur.

The table below shows the delay between the previous failed attempt and the next retry.

📘

Note:

• If the endpoint is disabled or deleted, the system stops retrying immediately.
• You can manually trigger tests for disabled endpoints from the RiskOS™ Dashboard.
• For auto-enrolled transactions, retries will continue indefinitely until a successful delivery (2xx response) occurs.

Security requirements

• The endpoint URL must be publicly accessible.
• The server must be configured to use HTTPS and TLS 1.2 (or later).
• The TLS certificate installed on the server must be uploaded to RiskOS™ when registering the endpoint.
• The endpoint should only accept requests from the following IPs:

Production

• 34.230.131.83
• 34.199.1.104
• 35.199.32.202/32

2. Register the endpoint in RiskOS™

Follow the steps below to create a webhook for Watchlist Monitoring or Case Management events in the RiskOS™ Dashboard:

📘

Note:

To limit traffic, configure your endpoint to receive only the event types required for your integration – either Case Management or Monitoring.

1. Go to Developer Workbench > Webhooks.
2. Select the Watchlist Alerts tab.
3. Click New Webhook.

4. Fill out the following fields:
   • Feature Type: Select the type of Watchlist event you want to subscribe to:
     • Monitoring: Receive events when watchlists are updated for monitored entities.
     • Case Management: Receive events when a case is approved or closed in the RiskOS™ Dashboard.
   • Communication Mode: Choose how you'd like to receive notifications:
     • Webhook: Sends an HTTPS POST request to your specified endpoint.
     • Email: Sends event details via email.
   • Subscription Channel Name: A unique name to identify this webhook subscription.
   • Webhook URL: Only applicable for Communication Mode Webhook. Provide the publicly accessible HTTPS endpoint where events should be delivered.
   • Email: Only applicable for Communication Mode Email. Provide valid email address
   • Alert Types: Configure the event types (Add, Change, Delete) that you want to be notified.
   • (Optional) Click Show Advanced to configure:
     • Secret Key: Add a token to verify the authenticity of incoming events.
     • TLS Certificate: Upload the TLS certificate used by your server. Supported formats include: .PEM, .CSR, .CER, .CRT, .KEY.
   • Click Test to send a test event. If your endpoint returns a 200 OK, a "Validation complete" message is displayed.
   • Click Create to create the webhook.

Edit or disable a webhook

To make changes to an existing webhook, click the three-dot menu next to it and choose View/Edit or Deactivate from the menu.

Troubleshooting failed webhooks

If your webhook isn’t receiving events, use the following checklist to identify and resolve common issues:

• Confirm public access Ensure your webhook endpoint is publicly accessible over the internet.

• Check for a valid response The endpoint must return an HTTP 200 OK status. Use tools like Hurl.it to test the response.

• Allow traffic from Socure IPs Verify your server allows traffic from the specified IP ranges.

• Validate TLS certificate If you're using certificate pinning, ensure the certificate is valid and trusted by the server receiving the request.

📘

Note:

Self-signed certificates are not supported.

• Disable custom headers Ensure custom headers are not required for processing the request.

• Still having issues? Contact your Solutions Consultant team and include the webhook endpoint URL for further investigation.

Test your webhook endpoint

You can manually test your webhook endpoint from the RiskOS™ Dashboard to confirm it’s set up correctly.

1. Go to Developer Workbench > Webhooks.
2. Select the Watchlist Alerts tab.
3. Locate the webhook you want to test.
4. Click the three-dot menu next to the webhook.
5. Click View/Edit option
6. Select Test.

This triggers a sample event to be sent to your configured endpoint. If your endpoint responds with 200 OK, the test is considered successful and you’ll see a “Validation complete” confirmation message.

---

Send notifications to your email

If you configured watchlist webhooks to receive email alerts, you will receive automated email notifications when a monitored entity is matched, updated, or removed from a global watchlist.

Sanctions and Enforcement monitoring email notification

Triggered when a monitored entity matches a sanctions or enforcement watchlist.

The alert includes key details such as match fields and status (e.g., Added, Updated, Removed).

Adverse Media monitoring email notification

Triggered when a monitored entity matches an adverse media source in your configured watchlist.