openapi: 3.2.0 info: title: Explorer Webhook API description: 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. version: 2.0.0 servers: - url: https://api.instantly.ai description: Instantly API Server security: - ApiKeyAuth: [] tags: - name: Webhook description: A webhook subscription for receiving event notifications x-group: Webhook paths: /api/v2/webhooks: get: operationId: listWebhook summary: List webhooks tags: - Webhook description: List all webhooks for the workspace with optional filters parameters: - schema: type: integer minimum: 1 maximum: 100 example: 10 example: 10 in: query name: limit required: false description: The number of items to return - schema: type: string example: 01956fbd-0eb1-72db-a565-82977a586084 example: 01956fbd-0eb1-72db-a565-82977a586084 in: query name: starting_after required: false description: 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. - schema: type: string format: uuid example: 019ffad2-9cba-73e6-9ae2-c6baedb90d09 example: 019ffad2-9cba-73e6-9ae2-c6baedb90d09 in: query name: campaign required: false description: Filter by campaign ID - schema: type: string enum: - all_events - email_sent - email_opened - email_link_clicked - reply_received - email_bounced - lead_unsubscribed - campaign_completed - account_error - lead_neutral - lead_interested - lead_not_interested - lead_meeting_booked - lead_meeting_completed - lead_closed - lead_out_of_office - lead_wrong_person example: all_events examples: all_events: value: all_events email_sent: value: email_sent in: query name: event_type required: false description: Filter by event type (e.g., email_sent, lead_interested, all_events) responses: '200': description: The list of Webhook content: application/json: schema: type: object properties: items: type: array description: The list of Webhook items: $ref: '#/components/schemas/Webhook' next_starting_after: type: string examples: - 019ffad2-9cba-73e6-9ae2-c6bb14cb75ce - '2026-08-13T11:12:14.522Z' description: 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: 019ffad2-9cba-73e6-9ae2-c6bb14cb75ce additionalProperties: false required: - items '401': description: This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked) content: application/json: schema: type: object properties: statusCode: type: number enum: - 401 examples: - 401 example: 401 error: type: string enum: - Unauthorized examples: - Unauthorized example: Unauthorized message: type: string examples: - Missing Authorization header example: Missing Authorization header required: - statusCode - error - message '402': description: This request cannot be fulfilled because the workspace does not have an active paid plan content: application/json: schema: type: object properties: statusCode: type: number enum: - 402 examples: - 402 example: 402 error: type: string enum: - Payment Required examples: - Payment Required example: Payment Required message: type: string examples: - Workspace does not have an active paid plan example: Workspace does not have an active paid plan required: - statusCode - error - message '404': description: The requested resource was not found content: application/json: schema: type: object properties: statusCode: type: number enum: - 404 examples: - 404 example: 404 error: type: string enum: - Not Found examples: - Not Found example: Not Found message: type: string examples: - Resource not found example: Resource not found required: - statusCode - error - message '429': description: You have exceeded the rate limit. Please check the rate limit docs for more information. content: application/json: schema: type: object properties: statusCode: type: number enum: - 429 examples: - 429 example: 429 error: type: string enum: - Too Many Requests examples: - Too Many Requests example: Too Many Requests message: type: string examples: - Rate limit exceeded example: Rate limit exceeded required: - statusCode - error - message post: operationId: createWebhook summary: Create webhook tags: - Webhook description: 'Requires one of the following scopes: `webhooks:create`, `webhooks:all`, `all:create`, `all:all`' requestBody: content: application/json: schema: title: CreateWebhook description: The Webhook to create type: object properties: campaign: type: - string - 'null' description: Optional campaign UUID to filter events (null = all campaigns in workspace) format: uuid example: 019ffad2-5cf8-732d-8cf0-41466f7573b6 name: type: - string - 'null' description: Optional user-defined name for the webhook example: Zapier Positive Replies target_hook_url: type: string description: Target URL to send webhook payloads format: uri pattern: ^https?:// example: https://webhook.site/unique-url event_type: type: - string - 'null' description: Type of event to trigger the webhook (null for custom label events). Set to "all_events" to subscribe to all events - including custom label events enum: - all_events - email_sent - email_opened - email_link_clicked - reply_received - email_bounced - lead_unsubscribed - campaign_completed - account_error - lead_neutral - lead_interested - lead_not_interested - lead_meeting_booked - lead_meeting_completed - lead_closed - lead_out_of_office - lead_wrong_person - lead_no_show - supersearch_enrichment_completed example: email_sent custom_interest_value: type: - number - 'null' description: Custom interest value - corresponds to LeadLabel.interest_status (used for custom label events) example: 1 headers: type: - object - 'null' description: Optional HTTP headers to include when delivering webhook payloads (key-value pairs) additionalProperties: type: string examples: - Basic dXNlcm5hbWU6cGFzc3dvcmQ= example: Basic dXNlcm5hbWU6cGFzc3dvcmQ= example: Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ= required: - target_hook_url additionalProperties: false required: true description: The Webhook to create responses: '200': description: The Webhook content: application/json: schema: $ref: '#/components/schemas/Webhook' '400': description: Invalid request body (e.g. missing required fields, or invalid field values) content: application/json: schema: type: object properties: statusCode: type: number enum: - 400 examples: - 400 example: 400 error: type: string enum: - Bad Request examples: - Bad Request example: Bad Request message: type: string examples: - body must have required property 'name' example: body must have required property 'name' required: - statusCode - error - message '401': description: This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked) content: application/json: schema: type: object properties: statusCode: type: number enum: - 401 examples: - 401 example: 401 error: type: string enum: - Unauthorized examples: - Unauthorized example: Unauthorized message: type: string examples: - Missing Authorization header example: Missing Authorization header required: - statusCode - error - message '402': description: This request cannot be fulfilled because the workspace does not have an active paid plan content: application/json: schema: type: object properties: statusCode: type: number enum: - 402 examples: - 402 example: 402 error: type: string enum: - Payment Required examples: - Payment Required example: Payment Required message: type: string examples: - Workspace does not have an active paid plan example: Workspace does not have an active paid plan required: - statusCode - error - message '404': description: The requested resource was not found content: application/json: schema: type: object properties: statusCode: type: number enum: - 404 examples: - 404 example: 404 error: type: string enum: - Not Found examples: - Not Found example: Not Found message: type: string examples: - Resource not found example: Resource not found required: - statusCode - error - message '429': description: You have exceeded the rate limit. Please check the rate limit docs for more information. content: application/json: schema: type: object properties: statusCode: type: number enum: - 429 examples: - 429 example: 429 error: type: string enum: - Too Many Requests examples: - Too Many Requests example: Too Many Requests message: type: string examples: - Rate limit exceeded example: Rate limit exceeded required: - statusCode - error - message /api/v2/webhooks/{id}: get: operationId: getWebhook summary: Get webhook tags: - Webhook description: 'Requires one of the following scopes: `webhooks:read`, `webhooks:all`, `all:read`, `all:all`' parameters: - schema: type: string format: uuid example: 019ffad2-9cbb-7b55-b289-6f24790a63d9 example: 019ffad2-9cbb-7b55-b289-6f24790a63d9 in: path name: id required: true description: The ID of the requested item responses: '200': description: The requested Webhook content: application/json: schema: $ref: '#/components/schemas/Webhook' '401': description: This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked) content: application/json: schema: type: object properties: statusCode: type: number enum: - 401 examples: - 401 example: 401 error: type: string enum: - Unauthorized examples: - Unauthorized example: Unauthorized message: type: string examples: - Missing Authorization header example: Missing Authorization header required: - statusCode - error - message '402': description: This request cannot be fulfilled because the workspace does not have an active paid plan content: application/json: schema: type: object properties: statusCode: type: number enum: - 402 examples: - 402 example: 402 error: type: string enum: - Payment Required examples: - Payment Required example: Payment Required message: type: string examples: - Workspace does not have an active paid plan example: Workspace does not have an active paid plan required: - statusCode - error - message '404': description: The requested resource was not found content: application/json: schema: type: object properties: statusCode: type: number enum: - 404 examples: - 404 example: 404 error: type: string enum: - Not Found examples: - Not Found example: Not Found message: type: string examples: - Resource not found example: Resource not found required: - statusCode - error - message '429': description: You have exceeded the rate limit. Please check the rate limit docs for more information. content: application/json: schema: type: object properties: statusCode: type: number enum: - 429 examples: - 429 example: 429 error: type: string enum: - Too Many Requests examples: - Too Many Requests example: Too Many Requests message: type: string examples: - Rate limit exceeded example: Rate limit exceeded required: - statusCode - error - message patch: operationId: patchWebhook summary: Patch webhook tags: - Webhook description: 'Requires one of the following scopes: `webhooks:update`, `webhooks:all`, `all:update`, `all:all`' requestBody: content: application/json: schema: type: object properties: campaign: type: - string - 'null' description: Optional campaign UUID to filter events (null = all campaigns in workspace) format: uuid example: 019ffad2-5cf8-732d-8cf0-41466f7573b6 name: type: - string - 'null' description: Optional user-defined name for the webhook example: Zapier Positive Replies target_hook_url: type: string description: Target URL to send webhook payloads format: uri pattern: ^https?:// example: https://webhook.site/unique-url event_type: type: - string - 'null' description: Type of event to trigger the webhook (null for custom label events). Set to "all_events" to subscribe to all events - including custom label events enum: - all_events - email_sent - email_opened - email_link_clicked - reply_received - email_bounced - lead_unsubscribed - campaign_completed - account_error - lead_neutral - lead_interested - lead_not_interested - lead_meeting_booked - lead_meeting_completed - lead_closed - lead_out_of_office - lead_wrong_person - lead_no_show - supersearch_enrichment_completed example: email_sent custom_interest_value: type: - number - 'null' description: Custom interest value - corresponds to LeadLabel.interest_status (used for custom label events) example: 1 headers: type: - object - 'null' description: Optional HTTP headers to include when delivering webhook payloads (key-value pairs) additionalProperties: type: string examples: - Basic dXNlcm5hbWU6cGFzc3dvcmQ= example: Basic dXNlcm5hbWU6cGFzc3dvcmQ= example: Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ= required: [] additionalProperties: false minProperties: 1 parameters: - schema: type: string format: uuid example: 019ffad2-9cbb-7b55-b289-6f25e7a8b91e example: 019ffad2-9cbb-7b55-b289-6f25e7a8b91e in: path name: id required: true description: The ID of the item to update responses: '200': description: The updated Webhook content: application/json: schema: $ref: '#/components/schemas/Webhook' '401': description: This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked) content: application/json: schema: type: object properties: statusCode: type: number enum: - 401 examples: - 401 example: 401 error: type: string enum: - Unauthorized examples: - Unauthorized example: Unauthorized message: type: string examples: - Missing Authorization header example: Missing Authorization header required: - statusCode - error - message '402': description: This request cannot be fulfilled because the workspace does not have an active paid plan content: application/json: schema: type: object properties: statusCode: type: number enum: - 402 examples: - 402 example: 402 error: type: string enum: - Payment Required examples: - Payment Required example: Payment Required message: type: string examples: - Workspace does not have an active paid plan example: Workspace does not have an active paid plan required: - statusCode - error - message '404': description: The requested resource was not found content: application/json: schema: type: object properties: statusCode: type: number enum: - 404 examples: - 404 example: 404 error: type: string enum: - Not Found examples: - Not Found example: Not Found message: type: string examples: - Resource not found example: Resource not found required: - statusCode - error - message '429': description: You have exceeded the rate limit. Please check the rate limit docs for more information. content: application/json: schema: type: object properties: statusCode: type: number enum: - 429 examples: - 429 example: 429 error: type: string enum: - Too Many Requests examples: - Too Many Requests example: Too Many Requests message: type: string examples: - Rate limit exceeded example: Rate limit exceeded required: - statusCode - error - message delete: operationId: deleteWebhook summary: Delete webhook tags: - Webhook description: 'Requires one of the following scopes: `webhooks:delete`, `webhooks:all`, `all:delete`, `all:all`' requestBody: content: application/json: schema: type: 'null' example: null parameters: - schema: type: string format: uuid example: 019ffad2-9cbc-7b8e-b2d3-1bdae53ff2eb example: 019ffad2-9cbc-7b8e-b2d3-1bdae53ff2eb in: path name: id required: true description: The ID of the item to delete responses: '200': description: The deleted Webhook content: application/json: schema: $ref: '#/components/schemas/Webhook' '401': description: This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked) content: application/json: schema: type: object properties: statusCode: type: number enum: - 401 examples: - 401 example: 401 error: type: string enum: - Unauthorized examples: - Unauthorized example: Unauthorized message: type: string examples: - Missing Authorization header example: Missing Authorization header required: - statusCode - error - message '402': description: This request cannot be fulfilled because the workspace does not have an active paid plan content: application/json: schema: type: object properties: statusCode: type: number enum: - 402 examples: - 402 example: 402 error: type: string enum: - Payment Required examples: - Payment Required example: Payment Required message: type: string examples: - Workspace does not have an active paid plan example: Workspace does not have an active paid plan required: - statusCode - error - message '404': description: The requested resource was not found content: application/json: schema: type: object properties: statusCode: type: number enum: - 404 examples: - 404 example: 404 error: type: string enum: - Not Found examples: - Not Found example: Not Found message: type: string examples: - Resource not found example: Resource not found required: - statusCode - error - message '429': description: You have exceeded the rate limit. Please check the rate limit docs for more information. content: application/json: schema: type: object properties: statusCode: type: number enum: - 429 examples: - 429 example: 429 error: type: string enum: - Too Many Requests examples: - Too Many Requests example: Too Many Requests message: type: string examples: - Rate limit exceeded example: Rate limit exceeded required: - statusCode - error - message /api/v2/webhooks/event-types: get: operationId: listWebhookEventTypes summary: List available event types tags: - Webhook description: Get all available webhook event types including custom labels responses: '200': description: Default Response content: application/json: schema: type: object properties: event_types: type: array items: type: object properties: id: type: string example: email_sent label: type: string example: Email Sent type: type: string example: standard '401': description: This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked) content: application/json: schema: type: object properties: statusCode: type: number enum: - 401 examples: - 401 example: 401 error: type: string enum: - Unauthorized examples: - Unauthorized example: Unauthorized message: type: string examples: - Missing Authorization header example: Missing Authorization header required: - statusCode - error - message '402': description: This request cannot be fulfilled because the workspace does not have an active paid plan content: application/json: schema: type: object properties: statusCode: type: number enum: - 402 examples: - 402 example: 402 error: type: string enum: - Payment Required examples: - Payment Required example: Payment Required message: type: string examples: - Workspace does not have an active paid plan example: Workspace does not have an active paid plan required: - statusCode - error - message '404': description: The requested resource was not found content: application/json: schema: type: object properties: statusCode: type: number enum: - 404 examples: - 404 example: 404 error: type: string enum: - Not Found examples: - Not Found example: Not Found message: type: string examples: - Resource not found example: Resource not found required: - statusCode - error - message '429': description: You have exceeded the rate limit. Please check the rate limit docs for more information. content: application/json: schema: type: object properties: statusCode: type: number enum: - 429 examples: - 429 example: 429 error: type: string enum: - Too Many Requests examples: - Too Many Requests example: Too Many Requests message: type: string examples: - Rate limit exceeded example: Rate limit exceeded required: - statusCode - error - message /api/v2/webhooks/{id}/test: post: operationId: testWebhook summary: Test a webhook tags: - Webhook description: Send a test payload to a webhook URL to verify it is working parameters: - schema: type: string format: uuid example: 019ffad2-9cbd-765b-a65b-d6d9e55bbb22 example: 019ffad2-9cbd-765b-a65b-d6d9e55bbb22 in: path name: id required: true responses: '200': description: Default Response content: application/json: schema: type: object properties: success: type: boolean example: true message: type: string example: Webhook test successful response_time_ms: type: number example: 250 status_code: type: number example: 200 error: type: string example: Connection timeout '401': description: This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked) content: application/json: schema: type: object properties: statusCode: type: number enum: - 401 examples: - 401 example: 401 error: type: string enum: - Unauthorized examples: - Unauthorized example: Unauthorized message: type: string examples: - Missing Authorization header example: Missing Authorization header required: - statusCode - error - message '402': description: This request cannot be fulfilled because the workspace does not have an active paid plan content: application/json: schema: type: object properties: statusCode: type: number enum: - 402 examples: - 402 example: 402 error: type: string enum: - Payment Required examples: - Payment Required example: Payment Required message: type: string examples: - Workspace does not have an active paid plan example: Workspace does not have an active paid plan required: - statusCode - error - message '404': description: The requested resource was not found content: application/json: schema: type: object properties: statusCode: type: number enum: - 404 examples: - 404 example: 404 error: type: string enum: - Not Found examples: - Not Found example: Not Found message: type: string examples: - Resource not found example: Resource not found required: - statusCode - error - message '429': description: You have exceeded the rate limit. Please check the rate limit docs for more information. content: application/json: schema: type: object properties: statusCode: type: number enum: - 429 examples: - 429 example: 429 error: type: string enum: - Too Many Requests examples: - Too Many Requests example: Too Many Requests message: type: string examples: - Rate limit exceeded example: Rate limit exceeded required: - statusCode - error - message /api/v2/webhooks/{id}/resume: post: operationId: resumeWebhook summary: Resume a webhook tags: - Webhook description: 'Resume a webhook that was disabled due to repeated delivery failures Requires one of the following scopes: `webhooks:update`, `webhooks:all`, `all:update`, `all:all`' parameters: - schema: type: string format: uuid example: 019ffad2-9cbd-765b-a65b-d6da9c5492dd example: 019ffad2-9cbd-765b-a65b-d6da9c5492dd in: path name: id required: true responses: '200': description: The requested Webhook content: application/json: schema: $ref: '#/components/schemas/Webhook' '401': description: This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked) content: application/json: schema: type: object properties: statusCode: type: number enum: - 401 examples: - 401 example: 401 error: type: string enum: - Unauthorized examples: - Unauthorized example: Unauthorized message: type: string examples: - Missing Authorization header example: Missing Authorization header required: - statusCode - error - message '402': description: This request cannot be fulfilled because the workspace does not have an active paid plan content: application/json: schema: type: object properties: statusCode: type: number enum: - 402 examples: - 402 example: 402 error: type: string enum: - Payment Required examples: - Payment Required example: Payment Required message: type: string examples: - Workspace does not have an active paid plan example: Workspace does not have an active paid plan required: - statusCode - error - message '404': description: The requested resource was not found content: application/json: schema: type: object properties: statusCode: type: number enum: - 404 examples: - 404 example: 404 error: type: string enum: - Not Found examples: - Not Found example: Not Found message: type: string examples: - Resource not found example: Resource not found required: - statusCode - error - message '429': description: You have exceeded the rate limit. Please check the rate limit docs for more information. content: application/json: schema: type: object properties: statusCode: type: number enum: - 429 examples: - 429 example: 429 error: type: string enum: - Too Many Requests examples: - Too Many Requests example: Too Many Requests message: type: string examples: - Rate limit exceeded example: Rate limit exceeded required: - statusCode - error - message components: schemas: Webhook: title: Webhook description: A webhook subscription for receiving event notifications x-tags: - Schemas - Webhook type: object properties: id: type: string description: Unique identifier for the webhook (UUID) readOnly: true format: uuid example: 019ffad2-5cf8-732d-8cf0-4144af749c8b organization: type: string description: Organization (workspace) UUID that owns this webhook readOnly: true format: uuid example: 019ffad2-5cf8-732d-8cf0-4145e239bac6 campaign: type: - 'null' - string description: Optional campaign UUID to filter events (null = all campaigns in workspace) format: uuid example: 019ffad2-5cf8-732d-8cf0-41466f7573b6 name: type: - 'null' - string description: Optional user-defined name for the webhook example: Zapier Positive Replies target_hook_url: type: string description: Target URL to send webhook payloads format: uri pattern: ^https?:// example: https://webhook.site/unique-url event_type: type: - 'null' - string description: Type of event to trigger the webhook (null for custom label events). Set to "all_events" to subscribe to all events - including custom label events enum: - all_events - email_sent - email_opened - email_link_clicked - reply_received - email_bounced - lead_unsubscribed - campaign_completed - account_error - lead_neutral - lead_interested - lead_not_interested - lead_meeting_booked - lead_meeting_completed - lead_closed - lead_out_of_office - lead_wrong_person - lead_no_show - supersearch_enrichment_completed example: email_sent custom_interest_value: type: - 'null' - number description: Custom interest value - corresponds to LeadLabel.interest_status (used for custom label events) example: 1 headers: type: - 'null' - object description: Optional HTTP headers to include when delivering webhook payloads (key-value pairs) additionalProperties: type: string examples: - Basic dXNlcm5hbWU6cGFzc3dvcmQ= example: Basic dXNlcm5hbWU6cGFzc3dvcmQ= example: Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ= timestamp_created: type: string description: Timestamp when the webhook was created readOnly: true format: date-time example: '2026-08-13T11:11:58.201Z' status: type: - 'null' - number description: 'Webhook status: 1 = active, -1 = error (disabled due to delivery failures)' readOnly: true example: 1 timestamp_error: type: - 'null' - string description: Timestamp when webhook was disabled due to delivery failures (null if active) readOnly: true format: date-time example: '2026-08-13T11:11:58.201Z' required: - id - organization - target_hook_url - timestamp_created additionalProperties: false securitySchemes: ApiKeyAuth: type: http scheme: bearer