Webhooks let Seamless push completed research results to your server the moment enrichment finishes, without requiring you to poll for status. When research completes, the platform sends aDocumentation Index
Fetch the complete documentation index at: https://docs.seamless.ai/llms.txt
Use this file to discover all available pages before exploring further.
POST request containing the enriched record to the HTTPS endpoint you configure. Your server validates the shared secret in the request header, processes the payload, and returns an HTTP 2xx response to acknowledge receipt.
Prerequisites
Before you set up webhooks:- Authenticate with an API key (
Tokenheader) or OAuth (Authorization: Bearer). - Create a public HTTPS endpoint that accepts
POSTrequests and is reachable from the internet. - In your Seamless account, go to Settings → Webhooks, create a webhook, and select the event type:
company-researchedorcontact-researched.
How delivery works
Event payloads
| Event | Fires when | Body shape |
|---|---|---|
company-researched | Company research completes | Company object — see Company Research in the public API reference |
contact-researched | Contact research completes | Contact object — see Contact Research |
apiResearchId field corresponds to the requestId from your research response. Use it to match webhook deliveries to in-flight jobs.
Webhook setup
Submit a research request
Call Research companies or Research contacts to start enrichment. Save the
requestId returned in the response.Wait for the platform to send the event
When research completes, Seamless sends a
POST request to your configured webhook endpoint. The request body contains the enriched record as a JSON object.Validate the webhook secret
Read the
x-seamless-webhook-secret header from the incoming request and compare it to the shared secret you configured in Settings → Webhooks. Reject requests where the values do not match.Parse the request body and process the event
Parse the JSON body and extract the enriched data. Run your application logic — store the record, trigger a downstream action, or pass it to another system.
Receiver code examples
Test your endpoint
Use thiscurl command to send a test event to your local receiver before deploying:
Use polling instead
If you prefer a request-response pattern or cannot expose a public HTTPS endpoint, use polling:- Submit a research request using Research companies or Research contacts.
- Save the
requestIdfrom the response. - Call Poll company research results or Poll contact research results with your
requestIdat a regular interval until thestatusfield returnsdone.
Troubleshooting
Your endpoint does not receive events
Your endpoint does not receive events
Confirm all of the following:
- A webhook exists in Settings → Webhooks for your account.
- The event type is set to
company-researchedorcontact-researched, depending on what you submitted. - Your endpoint is publicly reachable over HTTPS — local addresses such as
localhostwill not receive deliveries from the platform.
Your endpoint returns 401
Your endpoint returns 401
A
401 response means the secret validation failed. Check that the value of the x-seamless-webhook-secret header in the incoming request matches your configured shared secret exactly, including case and whitespace. Verify that the secret is correctly set in your deployed environment’s variables.Your endpoint returns 400
Your endpoint returns 400
A
400 response means the request body was rejected. Confirm that your endpoint accepts POST requests and that your application parses the body as JSON before attempting to read any fields. If you’re using Express, ensure express.json() middleware runs before your route handler.You want a request-response pattern instead
You want a request-response pattern instead
Use the polling endpoints. See Poll company research results for companies and Poll contact research results for contacts. Polling requires no public endpoint and works in any environment that can make outbound HTTP requests.
Related guides
End-to-end company workflow
A complete walkthrough of the company search, research, and result-retrieval flow.
End-to-end contact workflow
A complete walkthrough of the contact search, research, and result-retrieval flow.
Choose the right workflow
Compare webhooks, polling, and org data endpoints to find the right delivery pattern for your use case.
Build a deterministic agent workflow
Automate research workflows with an AI agent using a structured, repeatable sequence of API calls.
Troubleshoot authentication and request failures
Diagnose and resolve common errors in authentication, research submissions, and webhook delivery.
