Webhook

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

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

A webhook subscription for receiving event notifications

idstring(uuid)read-onlyrequired

Unique identifier for the webhook (UUID)

Example: "01990bfc-25c8-77bc-a1f9-98635185a1ad"
organizationstring(uuid)read-onlyrequired

Organization (workspace) UUID that owns this webhook

Example: "01990bfc-25c8-77bc-a1f9-9864b55f9be9"
target_hook_urlstring(uri)^https?://required

Target URL to send webhook payloads

Example: "https://webhook.site/unique-url"
timestamp_createdstring(date-time)read-onlyrequired

Timestamp when the webhook was created

Example: "2025-09-02T19:51:38.184Z"
campaignnull or string(uuid)

Optional campaign UUID to filter events (null = all campaigns in workspace)

Example: "01990bfc-25c8-77bc-a1f9-9865a824d2ca"
event_typenull or string

Type of event to trigger the webhook (null for custom label events)

Enum"email_sent""email_opened""email_link_clicked""reply_received""email_bounced""lead_unsubscribed""campaign_completed""account_error""lead_neutral""lead_interested"
Example: "email_sent"
custom_interest_valuenull or number

Custom interest value - corresponds to LeadLabel.interest_status (used for custom label events)

Example: 1
{
  "id": "01990bfc-25c8-77bc-a1f9-98635185a1ad",
  "organization": "01990bfc-25c8-77bc-a1f9-9864b55f9be9",
  "campaign": "01990bfc-25c8-77bc-a1f9-9865a824d2ca",
  "target_hook_url": "https://webhook.site/unique-url",
  "event_type": "email_sent",
  "custom_interest_value": 1,
  "timestamp_created": "2025-09-02T19:51:38.184Z"
}

List webhooks

Request

List all webhooks for the workspace with optional filters

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
campaignstring(uuid)

Filter by campaign ID

Example: campaign=01990bfc-45c9-7268-af62-8c643b3ff729
event_typestring

Filter by event type (e.g., email_sent, lead_interested)

Enum"email_sent""email_opened""email_link_clicked""reply_received""email_bounced""lead_unsubscribed""campaign_completed""account_error""lead_neutral""lead_interested"
Example: event_type=email_sent
curl -i -X GET \
  'https://api.instantly.ai/api/v2/webhooks?campaign=01990bfc-45c9-7268-af62-8c643b3ff729&event_type=email_sent&limit=10&starting_after=01956fbd-0eb1-72db-a565-82977a586084' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

The list of Webhook

Bodyapplication/json
itemsArray of objects(Webhook)required
items[].​idstring(uuid)read-onlyrequired

Unique identifier for the webhook (UUID)

Example: "01990bfc-25c8-77bc-a1f9-98635185a1ad"
items[].​organizationstring(uuid)read-onlyrequired

Organization (workspace) UUID that owns this webhook

Example: "01990bfc-25c8-77bc-a1f9-9864b55f9be9"
items[].​target_hook_urlstring(uri)^https?://required

Target URL to send webhook payloads

Example: "https://webhook.site/unique-url"
items[].​timestamp_createdstring(date-time)read-onlyrequired

Timestamp when the webhook was created

Example: "2025-09-02T19:51:38.184Z"
items[].​campaignnull or string(uuid)

Optional campaign UUID to filter events (null = all campaigns in workspace)

Example: "01990bfc-25c8-77bc-a1f9-9865a824d2ca"
items[].​event_typenull or string

Type of event to trigger the webhook (null for custom label events)

Enum"email_sent""email_opened""email_link_clicked""reply_received""email_bounced""lead_unsubscribed""campaign_completed""account_error""lead_neutral""lead_interested"
Example: "email_sent"
items[].​custom_interest_valuenull or number

Custom interest value - corresponds to LeadLabel.interest_status (used for custom label events)

Example: 1
next_starting_afterstring

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

Example: "01990bfc-45c9-7268-af62-8c65ac249cef"
Response
application/json
{
  "items": [
    { … }
  ],
  "next_starting_after": "01990bfc-45c9-7268-af62-8c65ac249cef"
}

Create webhook

Request

Requires one of the following scopes: webhooks:create, webhooks:all, all:create, all:all

Bodyapplication/jsonrequired

The Webhook to create

target_hook_urlstring(uri)^https?://required

Target URL to send webhook payloads

Example: "https://webhook.site/unique-url"
campaignstring or null(uuid)

Optional campaign UUID to filter events (null = all campaigns in workspace)

Example: "01990bfc-25c8-77bc-a1f9-9865a824d2ca"
event_typestring or null

Type of event to trigger the webhook (null for custom label events)

Enum"email_sent""email_opened""email_link_clicked""reply_received""email_bounced""lead_unsubscribed""campaign_completed""account_error""lead_neutral""lead_interested"
Example: "email_sent"
custom_interest_valuenumber or null

Custom interest value - corresponds to LeadLabel.interest_status (used for custom label events)

Example: 1
curl -i -X POST \
  https://api.instantly.ai/api/v2/webhooks \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "target_hook_url": "https://webhook.site/unique-url"
  }'

Responses

The Webhook

Bodyapplication/json
idstring(uuid)read-onlyrequired

Unique identifier for the webhook (UUID)

Example: "01990bfc-25c8-77bc-a1f9-98635185a1ad"
organizationstring(uuid)read-onlyrequired

Organization (workspace) UUID that owns this webhook

Example: "01990bfc-25c8-77bc-a1f9-9864b55f9be9"
target_hook_urlstring(uri)^https?://required

Target URL to send webhook payloads

Example: "https://webhook.site/unique-url"
timestamp_createdstring(date-time)read-onlyrequired

Timestamp when the webhook was created

Example: "2025-09-02T19:51:38.184Z"
campaignnull or string(uuid)

Optional campaign UUID to filter events (null = all campaigns in workspace)

Example: "01990bfc-25c8-77bc-a1f9-9865a824d2ca"
event_typenull or string

Type of event to trigger the webhook (null for custom label events)

Enum"email_sent""email_opened""email_link_clicked""reply_received""email_bounced""lead_unsubscribed""campaign_completed""account_error""lead_neutral""lead_interested"
Example: "email_sent"
custom_interest_valuenull or number

Custom interest value - corresponds to LeadLabel.interest_status (used for custom label events)

Example: 1
Response
application/json
{
  "id": "01990bfc-25c8-77bc-a1f9-98635185a1ad",
  "organization": "01990bfc-25c8-77bc-a1f9-9864b55f9be9",
  "campaign": "01990bfc-25c8-77bc-a1f9-9865a824d2ca",
  "target_hook_url": "https://webhook.site/unique-url",
  "event_type": "email_sent",
  "custom_interest_value": 1,
  "timestamp_created": "2025-09-02T19:51:38.184Z"
}

Get webhook

Request

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

Path
idstring(uuid)required

The ID of the requested item

Example: 01990bfc-45cb-703f-8ec0-4e884f979785
curl -i -X GET \
  https://api.instantly.ai/api/v2/webhooks/01990bfc-45cb-703f-8ec0-4e884f979785 \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

The requested Webhook

Bodyapplication/json
idstring(uuid)read-onlyrequired

Unique identifier for the webhook (UUID)

Example: "01990bfc-25c8-77bc-a1f9-98635185a1ad"
organizationstring(uuid)read-onlyrequired

Organization (workspace) UUID that owns this webhook

Example: "01990bfc-25c8-77bc-a1f9-9864b55f9be9"
target_hook_urlstring(uri)^https?://required

Target URL to send webhook payloads

Example: "https://webhook.site/unique-url"
timestamp_createdstring(date-time)read-onlyrequired

Timestamp when the webhook was created

Example: "2025-09-02T19:51:38.184Z"
campaignnull or string(uuid)

Optional campaign UUID to filter events (null = all campaigns in workspace)

Example: "01990bfc-25c8-77bc-a1f9-9865a824d2ca"
event_typenull or string

Type of event to trigger the webhook (null for custom label events)

Enum"email_sent""email_opened""email_link_clicked""reply_received""email_bounced""lead_unsubscribed""campaign_completed""account_error""lead_neutral""lead_interested"
Example: "email_sent"
custom_interest_valuenull or number

Custom interest value - corresponds to LeadLabel.interest_status (used for custom label events)

Example: 1
Response
application/json
{
  "id": "01990bfc-25c8-77bc-a1f9-98635185a1ad",
  "organization": "01990bfc-25c8-77bc-a1f9-9864b55f9be9",
  "campaign": "01990bfc-25c8-77bc-a1f9-9865a824d2ca",
  "target_hook_url": "https://webhook.site/unique-url",
  "event_type": "email_sent",
  "custom_interest_value": 1,
  "timestamp_created": "2025-09-02T19:51:38.184Z"
}

Patch webhook

Request

Requires one of the following scopes: webhooks:update, webhooks:all, all:update, all:all

Path
idstring(uuid)required

The ID of the item to update

Example: 01990bfc-45cc-79d2-9565-1cd280dc33c8
Bodyapplication/json
non-empty
campaignstring or null(uuid)

Optional campaign UUID to filter events (null = all campaigns in workspace)

Example: "01990bfc-25c8-77bc-a1f9-9865a824d2ca"
target_hook_urlstring(uri)^https?://

Target URL to send webhook payloads

Example: "https://webhook.site/unique-url"
event_typestring or null

Type of event to trigger the webhook (null for custom label events)

Enum"email_sent""email_opened""email_link_clicked""reply_received""email_bounced""lead_unsubscribed""campaign_completed""account_error""lead_neutral""lead_interested"
Example: "email_sent"
custom_interest_valuenumber or null

Custom interest value - corresponds to LeadLabel.interest_status (used for custom label events)

Example: 1
curl -i -X PATCH \
  https://api.instantly.ai/api/v2/webhooks/01990bfc-45cc-79d2-9565-1cd280dc33c8 \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{}'

Responses

The updated Webhook

Bodyapplication/json
idstring(uuid)read-onlyrequired

Unique identifier for the webhook (UUID)

Example: "01990bfc-25c8-77bc-a1f9-98635185a1ad"
organizationstring(uuid)read-onlyrequired

Organization (workspace) UUID that owns this webhook

Example: "01990bfc-25c8-77bc-a1f9-9864b55f9be9"
target_hook_urlstring(uri)^https?://required

Target URL to send webhook payloads

Example: "https://webhook.site/unique-url"
timestamp_createdstring(date-time)read-onlyrequired

Timestamp when the webhook was created

Example: "2025-09-02T19:51:38.184Z"
campaignnull or string(uuid)

Optional campaign UUID to filter events (null = all campaigns in workspace)

Example: "01990bfc-25c8-77bc-a1f9-9865a824d2ca"
event_typenull or string

Type of event to trigger the webhook (null for custom label events)

Enum"email_sent""email_opened""email_link_clicked""reply_received""email_bounced""lead_unsubscribed""campaign_completed""account_error""lead_neutral""lead_interested"
Example: "email_sent"
custom_interest_valuenull or number

Custom interest value - corresponds to LeadLabel.interest_status (used for custom label events)

Example: 1
Response
application/json
{
  "id": "01990bfc-25c8-77bc-a1f9-98635185a1ad",
  "organization": "01990bfc-25c8-77bc-a1f9-9864b55f9be9",
  "campaign": "01990bfc-25c8-77bc-a1f9-9865a824d2ca",
  "target_hook_url": "https://webhook.site/unique-url",
  "event_type": "email_sent",
  "custom_interest_value": 1,
  "timestamp_created": "2025-09-02T19:51:38.184Z"
}

Delete webhook

Request

Requires one of the following scopes: webhooks:delete, webhooks:all, all:delete, all:all

Path
idstring(uuid)required

The ID of the item to delete

Example: 01990bfc-45cd-7c3f-b9c0-bb7f1b9c837c
Bodyapplication/json
null
curl -i -X DELETE \
  https://api.instantly.ai/api/v2/webhooks/01990bfc-45cd-7c3f-b9c0-bb7f1b9c837c \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json'

Responses

The deleted Webhook

Bodyapplication/json
idstring(uuid)read-onlyrequired

Unique identifier for the webhook (UUID)

Example: "01990bfc-25c8-77bc-a1f9-98635185a1ad"
organizationstring(uuid)read-onlyrequired

Organization (workspace) UUID that owns this webhook

Example: "01990bfc-25c8-77bc-a1f9-9864b55f9be9"
target_hook_urlstring(uri)^https?://required

Target URL to send webhook payloads

Example: "https://webhook.site/unique-url"
timestamp_createdstring(date-time)read-onlyrequired

Timestamp when the webhook was created

Example: "2025-09-02T19:51:38.184Z"
campaignnull or string(uuid)

Optional campaign UUID to filter events (null = all campaigns in workspace)

Example: "01990bfc-25c8-77bc-a1f9-9865a824d2ca"
event_typenull or string

Type of event to trigger the webhook (null for custom label events)

Enum"email_sent""email_opened""email_link_clicked""reply_received""email_bounced""lead_unsubscribed""campaign_completed""account_error""lead_neutral""lead_interested"
Example: "email_sent"
custom_interest_valuenull or number

Custom interest value - corresponds to LeadLabel.interest_status (used for custom label events)

Example: 1
Response
application/json
{
  "id": "01990bfc-25c8-77bc-a1f9-98635185a1ad",
  "organization": "01990bfc-25c8-77bc-a1f9-9864b55f9be9",
  "campaign": "01990bfc-25c8-77bc-a1f9-9865a824d2ca",
  "target_hook_url": "https://webhook.site/unique-url",
  "event_type": "email_sent",
  "custom_interest_value": 1,
  "timestamp_created": "2025-09-02T19:51:38.184Z"
}

List available event types

Request

Get all available webhook event types including custom labels

curl -i -X GET \
  https://api.instantly.ai/api/v2/webhooks/event-types \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Default Response

Bodyapplication/json
event_typesArray of objects
Response
application/json
{
  "event_types": [
    { … }
  ]
}

Test a webhook

Request

Send a test payload to a webhook URL to verify it is working

Path
idstring(uuid)required
Example: 01990bfc-45cf-70b5-8bf0-46adf9a7026b
curl -i -X POST \
  https://api.instantly.ai/api/v2/webhooks/01990bfc-45cf-70b5-8bf0-46adf9a7026b/test \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Default Response

Bodyapplication/json
successboolean
Example: true
messagestring
Example: "Webhook test successful"
response_time_msnumber
Example: 250
status_codenumber
Example: 200
errorstring
Example: "Connection timeout"
Response
application/json
{
  "success": true,
  "message": "Webhook test successful",
  "response_time_ms": 250,
  "status_code": 200,
  "error": "Connection timeout"
}

Schemas