Webhooks
Webhooks
Webhooks tell your system when something finishes or changes, so you do not have to poll.
Add an endpoint
There are two ways to receive events.
- Add an endpoint under Automation in the dashboard and choose the events it should receive. It applies to the whole workspace.
- Pass a
webhook_urlwhen you submit a bulk job. It is called once, for that job.
Your endpoint receives each event as a JSON POST.
Events
| Event | Source | Sent when |
|---|---|---|
bulk.completed | Bulk API | A bulk job has a result or an error for every row. |
monitor.job_change | Job Change Monitoring | A watched contact changed company or title. |
visitor.identified | Website Visitor ID | A visiting company or consenting person was identified. |
credits.low | Account | Your balance fell below the alert threshold you set. |
Payload
Every event has the same outer shape. data depends on the event type.
POST to your endpoint
{
"id": "evt_41c0f7d2a9",
"type": "bulk.completed",
"created_at": "2026-11-19T10:41:07Z",
"data": {
"job_id": "job_7c1d9a42",
"product": "phone-validation",
"rows": 10000,
"succeeded": 9640,
"failed": 360,
"credits_used": 9640,
"results_url": "https://api.1lookup.dev/v1/bulk/job_7c1d9a42/results"
}
}idstringrequiredUnique to this event. Use it to ignore duplicates.
typestringrequiredThe event type, such as bulk.completed.
created_atstring<date-time>requiredWhen the event happened, in UTC.
dataobjectrequiredThe event's own fields. See event types.
Delivery and retries
- Respond with any
2xxstatus within 10 seconds to acknowledge the event. - Other responses and timeouts are retried with increasing delays for up to 24 hours.
- Events can arrive more than once. Use the event
idto ignore duplicates. - Recent deliveries and their responses are listed on the endpoint's page in the dashboard, where you can also resend one.