Skip to main content

​
Prerequisites

Before you begin, make sure you have:
  1. A Verisoul API key (available from the Dashboard)
  2. A webhook endpoint where Verisoul can deliver results

​
Step 1: Configure Your Webhook Endpoint

Share your webhook endpoint URL with Verisoul. Your endpoint must:
  • Accept POST requests with JSON payloads
  • Respond with a 2xx HTTP status code on success
  • Be idempotent (Verisoul may retry delivery)
  • Verify webhook signatures for security (see Step 3)
Once configured, Verisoul will automatically deliver results to this endpoint when email analysis completes.

​
Step 2: Submit Emails

Submit emails to the POST /email endpoint. You can submit a single email or a batch of up to 5,000 emails.

Submit Email

Submit a single email with optional identity claims. Returns a request_id for webhook correlation.

Submit Email Batch

Submit up to 5,000 emails with per-email claims. Returns a batch_id for grouping webhook results.
The API responds immediately with a request_id (single) or batch_id (batch). This confirms the email has been accepted for processing — it does not contain the analysis results.

​
Step 3: Receive and Verify Webhook Results

Once analysis completes, Verisoul delivers a webhook to your configured endpoint with the event type email.intelligence.completed.

​
Webhook Signature Verification

All webhook requests include an x-signature header for authentication.
  • Each webhook subscription has a shared secret
  • Verisoul signs requests using HMAC-SHA256
  • The signature covers a timestamp, selected headers, and the raw request body
Always verify the signature before processing the payload. Use the raw request body (not a parsed/re-serialized version) and enforce a timestamp tolerance of ±5 minutes.

​
Processing the Payload

  1. Verify the webhook signature
  2. Check the status field — either success or error
  3. On success, use data.result.decision and data.result.risk_score for your business logic
  4. On error, inspect the error object for details
See the Webhook Payload Reference for the full payload structure and field definitions.

​
FAQ

Latency depends on whether Verisoul has previously analyzed the email or domain.
  • Invalid or previously analyzed emails: under 1 second
  • New email on a known domain: approximately 5 seconds
  • New domain never seen before: 30–60 seconds
Verisoul guarantees webhook delivery within 90 seconds of the initial request.
If your endpoint does not return a 2xx response, Verisoul retries delivery:
  • Up to 5 fast retries with increasing delays
  • Up to 5 slow retries approximately once per hour
Total retry window is approximately 5 hours. Webhooks may be delivered more than once, so your endpoint should be idempotent.
Calls to /email count toward your API key’s rate limit. If you need a higher limit, contact Verisoul.
All Verisoul webhooks are sent from:
34.71.198.163
You can allowlist this IP if your endpoint is behind a firewall. You should still verify webhook signatures regardless.