Webhooks & Integrations

What are webhooks?

Webhooks allow TradeLasso to automatically send data to your systems in real-time when specific events occur. Instead of polling our API for updates, webhooks push notifications to your endpoints instantly.

Common use cases include:

• Pushing screening results to your CRM or ERP system
• Sending compliance alerts to your internal tools
• Triggering workflows in your compliance management platform
• Logging events to your audit trail or SIEM
• Updating customer records when watchlist matches are detected

Supported events

TradeLasso can send webhooks for the following events:

Screening events

• screening.completed — A single screening finished (with or without matches)
• screening.match_found — A screening found one or more potential matches
• batch.completed — A batch screening job finished processing
• batch.match_found — A batch job found matches in one or more entities

Monitoring events

• monitor.alert — Watchlist monitoring detected a new match
• monitor.scan_completed — A scheduled monitor scan finished

Regulatory events

• regulatory.update — A sanctions list was updated
• regulatory.new_entity — A new entity was added to a list

Compliance events

• certificate.generated — A compliance certificate was created
• report.generated — A PDF compliance report was created

Creating a webhook

To create a webhook, go to Dashboard → Settings → Webhooks:

1. Click "Add Webhook"
2. Enter your endpoint URL (must be HTTPS for security)
3. Give your webhook a descriptive name
4. Select which events to subscribe to
5. (Optional) Add a secret key for signature verification
6. Click "Create" to activate the webhook

Testing your webhook

After creating a webhook, you should test it:

1. Click "Send Test Event" next to your webhook
2. Choose an event type to test
3. TradeLasso will send a sample payload to your endpoint
4. Verify your system received and processed the event correctly

Webhook payload format

All webhook payloads follow this structure:

{
  "event": "screening.completed",
  "timestamp": "2026-05-05T18:30:00Z",
  "data": {
    // Event-specific data
  },
  "account_id": "acc_abc123",
  "webhook_id": "wh_xyz789"
}

Example: screening.completed

{
  "event": "screening.completed",
  "timestamp": "2026-05-05T18:30:00Z",
  "data": {
    "screening_id": "scr_abc123",
    "entity_name": "Acme Corporation",
    "entity_country": "US",
    "match_count": 0,
    "status": "no_match",
    "lists_searched": ["OFAC SDN", "BIS Entity List", "EU Consolidated"],
    "screening_url": "https://tradelasso.com/dashboard/history/scr_abc123"
  },
  "account_id": "acc_abc123",
  "webhook_id": "wh_xyz789"
}

Example: monitor.alert

{
  "event": "monitor.alert",
  "timestamp": "2026-05-05T18:30:00Z",
  "data": {
    "alert_id": "alert_abc123",
    "monitor_id": "mon_xyz789",
    "monitor_name": "Active Customers",
    "entity_name": "John Smith",
    "entity_country": "RU",
    "match_score": 95,
    "list": "OFAC SDN",
    "previous_status": "no_match",
    "current_status": "potential_match",
    "alert_url": "https://tradelasso.com/dashboard/monitoring/alert_abc123"
  },
  "account_id": "acc_abc123",
  "webhook_id": "wh_xyz789"
}

Verifying webhook signatures

To ensure webhooks are genuinely from TradeLasso, we include a signature in the X-TradeLasso-Signature header:

X-TradeLasso-Signature: t=1683302400,v1=5f7d8a9b2c3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9

Verification steps

1. Extract the timestamp (t) and signature (v1) from the header
2. Concatenate: timestamp + "." + raw_request_body
3. Compute HMAC-SHA256 using your webhook secret
4. Compare the computed signature with v1
5. Reject the request if signatures don't match or timestamp is too old (>5 minutes)

Example verification (Node.js)

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const [t, v1] = signature.split(',').map(s => s.split('=')[1]);
  const signedPayload = `${t}.${payload}`;
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');
  
  const isValid = crypto.timingSafeEqual(
    Buffer.from(v1),
    Buffer.from(expectedSignature)
  );
  
  const age = Date.now() / 1000 - parseInt(t);
  return isValid && age < 300; // 5 minutes
}

Handling webhook deliveries

Best practices

• Respond quickly — Return a 2xx status code within 5 seconds to acknowledge receipt
• Process asynchronously — Queue the event for background processing rather than blocking the response
• Handle duplicates — Use the event ID to detect and ignore duplicate deliveries
• Verify signatures — Always validate the webhook signature before processing
• Monitor failures — Set up alerts for webhook delivery failures

Retry behavior

If your endpoint fails to respond or returns an error:

• TradeLasso will retry the delivery up to 3 times
• Retries use exponential backoff (5s, 25s, 125s)
• After 3 failures, the webhook is marked as failed
• You can manually retry failed deliveries from the dashboard

Webhook limits by plan

No-code integrations

TradeLasso webhooks work with any automation platform that supports custom HTTP webhooks. No special TradeLasso app or plugin is required — just paste your webhook URL.

Using with Zapier

1. In Zapier, create a new Zap and choose Webhooks by Zapier as the trigger
2. Select Catch Hook as the trigger event
3. Copy the webhook URL Zapier gives you
4. In TradeLasso, go to Dashboard → Webhooks and click Add Endpoint
5. Paste the Zapier URL, select your events, and click Create
6. Click Test in TradeLasso — Zapier will receive the test payload
7. In Zapier, click Test trigger to capture the data structure, then build your action

Using with Make.com

1. In Make.com, create a new Scenario and add a Webhooks module
2. Select Custom Webhook and copy the URL it generates
3. In TradeLasso, go to Dashboard → Webhooks and click Add Endpoint
4. Paste the Make.com URL, select your events, and click Create
5. Click Test in TradeLasso — Make.com will receive the payload
6. In Make.com, click Determine data structure to map the fields

Using with n8n

1. In n8n, add a Webhook node as your trigger
2. Set the method to POST and copy the webhook URL
3. In TradeLasso, add an endpoint with that URL and your chosen events
4. Click Test to send a test payload to n8n

Popular automation ideas

• Screening → Slack — Post match alerts to a compliance channel
• Screening → Google Sheets — Log all screenings to a spreadsheet
• Screening → CRM — Update customer records with screening results
• Monitor Alert → Email — Send notifications when watchlist matches are found
• Batch Complete → Airtable — Save batch results to a database

Monitoring webhook health

Track webhook performance in Dashboard → Settings → Webhooks:

• Delivery rate — Percentage of successful deliveries
• Response time — Average time your endpoint takes to respond
• Recent deliveries — View last 100 deliveries with status and payload
• Failed deliveries — See which deliveries failed and why
• Usage stats — Track deliveries against your monthly limit

Troubleshooting

Webhook not receiving events

• Verify your endpoint URL is correct and publicly accessible
• Check that your endpoint returns a 2xx status code
• Ensure your firewall allows incoming requests from TradeLasso IPs
• Verify you've subscribed to the correct event types
• Check the webhook logs for error messages

Signature verification failing

• Ensure you're using the raw request body (not parsed JSON)
• Verify your secret key matches the one in your webhook settings
• Check that your server's clock is synchronized (NTP)
• Make sure you're extracting the timestamp and signature correctly

High failure rate

• Check your endpoint's response time (should be <5 seconds)
• Verify your server has sufficient capacity to handle webhook volume
• Implement asynchronous processing to avoid timeouts
• Monitor your server logs for errors

Related documentation

• API Access — Programmatic access to TradeLasso
• Watchlist Monitoring — Automated re-screening
• Regulatory Alerts — List update notifications
• Plan Limits & Usage — View your webhook limits