Skip to content
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_url when you submit a bulk job. It is called once, for that job.

Your endpoint receives each event as a JSON POST.

Events

EventSourceSent when
bulk.completedBulk APIA bulk job has a result or an error for every row.
monitor.job_changeJob Change MonitoringA watched contact changed company or title.
visitor.identifiedWebsite Visitor IDA visiting company or consenting person was identified.
credits.lowAccountYour 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"
  }
}
idstringrequired

Unique to this event. Use it to ignore duplicates.

typestringrequired

The event type, such as bulk.completed.

created_atstring<date-time>required

When the event happened, in UTC.

dataobjectrequired

The event's own fields. See event types.

Delivery and retries

  • Respond with any 2xx status 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 id to ignore duplicates.
  • Recent deliveries and their responses are listed on the endpoint's page in the dashboard, where you can also resend one.

Next