Webhook Event

API Explorer (2.0.0)

The entire API V2 documentation is interactive and can be tested here. To the right side of every endpoint you will see a box with an example request. You can click on the "Try it" button to send a request to the server right from the docs. You will need to provide an API key by clicking the ApiKeyAuth_token blue text.

Languages
Servers
Instantly API Server

https://api.instantly.ai/

Mock server

https://developer.instantly.ai/_mock/api/v2/

Analytics

Endpoints related to analytics

Operations

Account

An email account that can be used to send campaigns

Operations

Campaign

A campaign that can be sent to a list of recipients

Operations

Email

A campaign email, a reply, a manually sent email, or any other email that's visible in the Unibox

Operations

Email Verification

A single email verification

Operations

Lead List

A list used to store leads

Operations

Inbox Placement Test

An inbox placement test

Operations

Inbox Placement Analytics

Analytics data for individual emails in inbox placement tests

Operations

Inbox Placement Blacklist & SpamAssassin Report

Report data for an inbox placement test

Operations

API Key

API Key

Operations

Account Campaign Mapping

Account Campaign Mapping

Operations

Lead

A lead entity representing an individual lead

Operations

Background Job

A background job that can be used to perform long-running tasks

Operations

Custom Tag

A custom tag for organizing and categorizing accounts and campaigns. You can use them as filters in apis that list accounts and campaigns.

Operations

Block List Entry

A blocked email or domain

Operations

Lead Label

A custom label for categorizing and managing leads

Operations

Workspace

A workspace entity representing a workspace

Operations

SuperSearch Enrichment

An enrichment can take different forms, such as email enrichment or LinkedIn enrichment. Leads may be imported from SuperSearch using the dedicated endpoint, or enriched directly within a list or campaign by attaching an enrichment to it.

Operations

Workspace Group Member

A member of a workspace group. You can use the endpoints within this entity to manage the members of a workspace group.

Operations

Workspace Member

A member of a workspace with associated user details

Operations

Campaign Subsequence

A subsequence entity representing a follow-up sequence

Operations

Audit Log

Audit log records for tracking system activities

Operations

Webhook

A webhook subscription for receiving event notifications

Operations

Webhook Event

A webhook event that was sent or attempted to be sent

Operations

Webhook Event

A webhook event that was sent or attempted to be sent

idstring(uuid)read-onlyrequired

Unique identifier for the webhook event (UUID)

Example: "019981cb-e611-7889-b23a-f047bb3e885e"
timestamp_createdstring(date-time)read-onlyrequired

Timestamp when the webhook event was created

Example: "2025-09-25T16:54:07.633Z"
timestamp_created_datestring(date)read-onlyrequired

Date when the webhook event was created (for partitioning)

Example: "2024-01-15"
organization_idstring(uuid)read-onlyrequired

Organization (workspace) UUID that owns this webhook event

Example: "019981cb-e611-7889-b23a-f0483eff78e1"
successbooleanread-onlyrequired

Whether the webhook call was successful

Example: true
retry_countnumberread-onlyrequired

Number of retry attempts made

Example: 0
will_retrybooleanread-onlyrequired

Whether the webhook will be retried

Example: false
webhook_urlstringread-onlyrequired

Target URL where the webhook was sent

Example: "https://webhook.site/unique-url"
payloadobjectread-only

JSON payload that was sent/attempted to be sent

status_codenull or numberread-only

HTTP status code received from the webhook endpoint (if any)

Example: 200
error_messagenull or stringread-only

Error message if the webhook failed

Example: "Connection timeout"
timestamp_next_retrynull or string(date-time)read-only

Timestamp for the next retry attempt (if applicable)

Example: "2025-09-25T16:54:07.633Z"
retry_group_idnull or string(uuid)read-only

UUID for grouping retry attempts

Example: "019981cb-e611-7889-b23a-f049dc97e40c"
retry_successfulnull or booleanread-only

Whether the retry was successful (for retry events)

Example: true
lead_emailnull or stringread-only

Email address of the lead associated with this webhook event

Example: "lead@example.com"
response_time_msnull or numberread-only

Response time in milliseconds for the webhook call

Example: 150
{
  "id": "019981cb-e611-7889-b23a-f047bb3e885e",
  "timestamp_created": "2025-09-25T16:54:07.633Z",
  "timestamp_created_date": "2024-01-15",
  "organization_id": "019981cb-e611-7889-b23a-f0483eff78e1",
  "payload": {},
  "success": true,
  "retry_count": 0,
  "will_retry": false,
  "webhook_url": "https://webhook.site/unique-url",
  "status_code": 200,
  "error_message": "Connection timeout",
  "timestamp_next_retry": "2025-09-25T16:54:07.633Z",
  "retry_group_id": "019981cb-e611-7889-b23a-f049dc97e40c",
  "retry_successful": true,
  "lead_email": "lead@example.com",
  "response_time_ms": 150
}

List webhook event

Request

Requires one of the following scopes: webhook_events:read, webhook_events:all, all:read, all:all

Query
limitinteger[ 1 .. 100 ]

The number of items to return

Example: limit=10
starting_afterstring

The ID of the last item in the previous page - used for pagination. You can use the value of the next_starting_after field from the previous response.

Example: starting_after=01956fbd-0eb1-72db-a565-82977a586084
successboolean

Filter by success status

Example: success=true
fromstring(date)

Inclusive start of the window (YYYY-MM-DD).

Example: from=2024-01-01
tostring(date)

Inclusive end of the window (YYYY-MM-DD).

Example: to=2024-01-31
searchstring

Search by exact webhook URL or lead email match

Example: search=https://webhook.site/unique-url
curl -i -X GET \
  'https://api.instantly.ai/api/v2/webhook-events?from=2024-01-01&limit=10&search=https%3A%2F%2Fwebhook.site%2Funique-url&starting_after=01956fbd-0eb1-72db-a565-82977a586084&success=true&to=2024-01-31' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

The list of Webhook Event

Bodyapplication/json
itemsArray of objects(Webhook Event)required

The list of Webhook Event

items[].​idstring(uuid)read-onlyrequired

Unique identifier for the webhook event (UUID)

Example: "019981cb-e611-7889-b23a-f047bb3e885e"
items[].​timestamp_createdstring(date-time)read-onlyrequired

Timestamp when the webhook event was created

Example: "2025-09-25T16:54:07.633Z"
items[].​timestamp_created_datestring(date)read-onlyrequired

Date when the webhook event was created (for partitioning)

Example: "2024-01-15"
items[].​organization_idstring(uuid)read-onlyrequired

Organization (workspace) UUID that owns this webhook event

Example: "019981cb-e611-7889-b23a-f0483eff78e1"
items[].​successbooleanread-onlyrequired

Whether the webhook call was successful

Example: true
items[].​retry_countnumberread-onlyrequired

Number of retry attempts made

Example: 0
items[].​will_retrybooleanread-onlyrequired

Whether the webhook will be retried

Example: false
items[].​webhook_urlstringread-onlyrequired

Target URL where the webhook was sent

Example: "https://webhook.site/unique-url"
items[].​payloadobjectread-only

JSON payload that was sent/attempted to be sent

items[].​status_codenull or numberread-only

HTTP status code received from the webhook endpoint (if any)

Example: 200
items[].​error_messagenull or stringread-only

Error message if the webhook failed

Example: "Connection timeout"
items[].​timestamp_next_retrynull or string(date-time)read-only

Timestamp for the next retry attempt (if applicable)

Example: "2025-09-25T16:54:07.633Z"
items[].​retry_group_idnull or string(uuid)read-only

UUID for grouping retry attempts

Example: "019981cb-e611-7889-b23a-f049dc97e40c"
items[].​retry_successfulnull or booleanread-only

Whether the retry was successful (for retry events)

Example: true
items[].​lead_emailnull or stringread-only

Email address of the lead associated with this webhook event

Example: "lead@example.com"
items[].​response_time_msnull or numberread-only

Response time in milliseconds for the webhook call

Example: 150
next_starting_afterstring

The filter for getting the next items after this one, this could either be a UUID, a timestamp, on an email depending on the specific API

Example: "019981cb-fc6b-770f-a9ef-a3756727ccff"
Response
application/json
{
  "items": [
    { … }
  ],
  "next_starting_after": "019981cb-fc6b-770f-a9ef-a3756727ccff"
}

Get webhook event

Request

Requires one of the following scopes: webhook_events:read, webhook_events:all, all:read, all:all

Path
idstring(uuid)required

The ID of the requested item

Example: 019981cb-fc6c-7723-8092-37fa0e2778a0
curl -i -X GET \
  https://api.instantly.ai/api/v2/webhook-events/019981cb-fc6c-7723-8092-37fa0e2778a0 \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

The requested Webhook Event

Bodyapplication/json
idstring(uuid)read-onlyrequired

Unique identifier for the webhook event (UUID)

Example: "019981cb-e611-7889-b23a-f047bb3e885e"
timestamp_createdstring(date-time)read-onlyrequired

Timestamp when the webhook event was created

Example: "2025-09-25T16:54:07.633Z"
timestamp_created_datestring(date)read-onlyrequired

Date when the webhook event was created (for partitioning)

Example: "2024-01-15"
organization_idstring(uuid)read-onlyrequired

Organization (workspace) UUID that owns this webhook event

Example: "019981cb-e611-7889-b23a-f0483eff78e1"
successbooleanread-onlyrequired

Whether the webhook call was successful

Example: true
retry_countnumberread-onlyrequired

Number of retry attempts made

Example: 0
will_retrybooleanread-onlyrequired

Whether the webhook will be retried

Example: false
webhook_urlstringread-onlyrequired

Target URL where the webhook was sent

Example: "https://webhook.site/unique-url"
payloadobjectread-only

JSON payload that was sent/attempted to be sent

status_codenull or numberread-only

HTTP status code received from the webhook endpoint (if any)

Example: 200
error_messagenull or stringread-only

Error message if the webhook failed

Example: "Connection timeout"
timestamp_next_retrynull or string(date-time)read-only

Timestamp for the next retry attempt (if applicable)

Example: "2025-09-25T16:54:07.633Z"
retry_group_idnull or string(uuid)read-only

UUID for grouping retry attempts

Example: "019981cb-e611-7889-b23a-f049dc97e40c"
retry_successfulnull or booleanread-only

Whether the retry was successful (for retry events)

Example: true
lead_emailnull or stringread-only

Email address of the lead associated with this webhook event

Example: "lead@example.com"
response_time_msnull or numberread-only

Response time in milliseconds for the webhook call

Example: 150
Response
application/json
{
  "id": "019981cb-e611-7889-b23a-f047bb3e885e",
  "timestamp_created": "2025-09-25T16:54:07.633Z",
  "timestamp_created_date": "2024-01-15",
  "organization_id": "019981cb-e611-7889-b23a-f0483eff78e1",
  "payload": {},
  "success": true,
  "retry_count": 0,
  "will_retry": false,
  "webhook_url": "https://webhook.site/unique-url",
  "status_code": 200,
  "error_message": "Connection timeout",
  "timestamp_next_retry": "2025-09-25T16:54:07.633Z",
  "retry_group_id": "019981cb-e611-7889-b23a-f049dc97e40c",
  "retry_successful": true,
  "lead_email": "lead@example.com",
  "response_time_ms": 150
}

Get overview aggregates for webhook events

Request

Get overview aggregates for webhook events including success/failure rates

Query
fromstring(date)

Inclusive start of the window (YYYY-MM-DD).

Example: from=2024-01-01
tostring(date)

Inclusive end of the window (YYYY-MM-DD).

Example: to=2024-01-31
curl -i -X GET \
  'https://api.instantly.ai/api/v2/webhook-events/summary?from=2024-01-01&to=2024-01-31' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Default Response

Bodyapplication/json
total_eventsnumberrequired

Total number of webhook events

Example: 100
successful_eventsnumberrequired

Total number of successful webhook events

Example: 100
failed_eventsnumberrequired

Total number of failed webhook events

Example: 100
success_ratenumberrequired

Percentage (0-100) of successful webhook calls

Example: 50
failure_ratenumberrequired

Percentage (0-100) of failed webhook calls

Example: 50
Response
application/json
{
  "total_events": 100,
  "successful_events": 100,
  "failed_events": 100,
  "success_rate": 50,
  "failure_rate": 50
}

Get overview aggregates for webhook events by date

Request

Get overview aggregates for webhook events by Date for charts

Query
fromstring(date)

Inclusive start of the window (YYYY-MM-DD).

Example: from=2024-01-01
tostring(date)

Inclusive end of the window (YYYY-MM-DD).

Example: to=2024-01-31
curl -i -X GET \
  'https://api.instantly.ai/api/v2/webhook-events/summary-by-date?from=2024-01-01&to=2024-01-31' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

List of webhook event KPIs grouped by date

Bodyapplication/json
itemsArray of objects
Response
application/json
{
  "items": [
    { … }
  ]
}

DFY Email Account Order

A Done-For-You email account order

Operations

Schemas