Hooks API — Fields Reference

View as Markdown OpenAPI

This article describes all fields available through the Hooks API. Use it as a reference when creating, reading, or deleting webhook subscriptions.

Overview

The Hooks API lets you manage webhook subscriptions programmatically. A webhook subscription tells Envoke to send an HTTP POST to your endpoint whenever a specific event — a new contact, a form submission, an email open, or a lead activity — occurs in your account.

Each subscription has four fields: a unique ID, an event type, a destination URL, and an optional filter.

All endpoints require HTTP Basic Auth using your API ID and API Key.

Fields

Field	Type	Read-only	Required on Create	Description
`id`	string	Yes	—	Unique 32-character hex identifier assigned on creation.
`type`	string (enum)	No (set on create only)	Yes	The event type that triggers this subscription.
`url`	string (URI)	No (set on create only)	Yes	The destination URL that receives HTTP POST payloads.
`filter`	object	No (set on create only)	No	Optional key-value conditions that must match before delivery.

Note: The Hooks API has no update endpoint, so type, url, and filter are set when the subscription is created and cannot be changed afterwards. To change one, delete the subscription and create a new one.

Field Details

`id`

Type: String
Read-only: Yes — assigned automatically on creation.
Format: 32-character lowercase hexadecimal string.
Example: "9f1c2a42baedb56c7e65b3eeaf1a8814"

Use this ID in GET /v1/hooks/{id}.json and DELETE /v1/hooks/{id}.json requests.

`type`

Type: String (enum)
Read-only: No — set on create; it cannot be changed afterwards.
Required on create: Yes

The event type that triggers delivery. Must be one of the following values:

Contact events

Value	Triggers when…
`new_contact`	A new contact is added to your account by any means.
`consent_change`	A contact’s consent status changes.

Submission events

Value	Triggers when…
`submission`	Any form submission occurs (generic, covers all submission types below).
`form_submission`	A contact submits a website form.
`preference_page_submission`	A contact submits a preference page form.
`api_submission`	A contact is added or updated via the API.
`import_submission`	A contact is added via a list import.
`ui_submission`	A contact is added manually in the Envoke UI.

Email activity events

Value	Triggers when…
`email_send`	Envoke hands an email to its sending server for delivery to a contact. Sent, not delivered: a later refusal by the recipient’s server fires `email_bounce`.
`email_open`	A contact opens an email.
`email_click`	A contact clicks a link in an email.
`email_autoresponder_send`	An autoresponder email is sent to a contact.
`email_bounce`	An email to a contact bounces or is refused (deferrals are not included).
`email_spam_report`	A contact reports an email as spam, through their mailbox provider or the Envoke preference page.
`email_delivery`	The recipient’s mail server accepts an email. Reserved for an upcoming release: you can subscribe now, but no events are delivered yet.

An account restricted from seeing contacts associated with email activity cannot subscribe to email_open or email_click: the request fails with Invalid webhook type: 'email_open'. The other email activity types are available to every account.

Lead events

Value	Triggers when…
`new_lead`	A new lead is created.
`passed_to_sales`	A lead is passed to the sales team.
`lead_update`	A lead record is updated.
`new_opportunity`	An opportunity is created on a lead.
`new_sale`	A sale is recorded on a lead.

`url`

Type: String (URI)
Read-only: No — set on create; it cannot be changed afterwards.
Required on create: Yes
Validation: Must begin with http:// or https://.
Example: "https://hooks.zapier.com/hooks/catch/123456/abcdef/"

Envoke sends an HTTP POST to this URL when a matching event fires. Your endpoint should return an HTTP 2xx status within 60 seconds to acknowledge delivery. A status of 400 or above, no response within 60 seconds, or a connection failure is retried once, 10 minutes later. If your endpoint returns HTTP 410 (Gone), the subscription is automatically removed. See Responses and retries.

A subscription is unique by type and url: a second subscription with the same type and URL is refused, whatever its filter (see Duplicate subscription). To route events for many contacts or messages, subscribe once per event type and route in your endpoint by contact_remote_id, contact_id, or message_id.

`filter`

Type: Object
Read-only: No — set on create; it cannot be changed afterwards.
Required on create: No — omit or pass {} to receive all events of the subscribed type.
Key type: String
Value type: Scalar (string, number, or boolean)

An optional set of key-value conditions. Before delivering an event, Envoke evaluates every key in the filter against the event payload. If all conditions match, the event is delivered. If any condition does not match, the event is silently skipped.

Values are compared as text, exactly and case-sensitively: the filter value and the payload value are both converted to strings, so 789 and "789" match the same events, true matches "1", and false matches "". A filter value of "" matches events whose field is empty or missing.

An empty object ({}) disables filtering — every event of the subscribed type is delivered.

Common filter keys by event type:

Event type(s)	Filter key	Description
`form_submission`, `submission`, `preference_page_submission`, `api_submission`, `import_submission`, `ui_submission`	`form_id`	Deliver only events from a specific form.
All email activity events	`message_id`	Deliver only events from a specific email message, by its ID.
All email activity events	`message_external_id`	Deliver only events from a specific email message, by its 32-character external ID. An alternative to `message_id`.
All email activity events	`contact_remote_id`	Deliver only events for a contact with a specific remote ID.
`email_bounce`	`bounce_type`	Deliver only one kind of bounce, for example `hard`.
`email_spam_report`	`source`	Deliver only spam reports from one source: `feedback_loop` or `envoke`.

The email activity events are email_send, email_open, email_click, email_autoresponder_send, email_bounce, email_spam_report, and email_delivery. Filter keys are matched against the delivered payload (see Webhook Payloads), so a key that is not in the payload (for example campaign_id) never matches and every event is skipped.

For a batched event type, the events a filter removes from a delivery still count towards your API limits whenever at least one event of the batch is delivered (see Ordering and duplicates).

Example filter values:

{ "form_id": "abc123def456" }

{ "message_id": "789" }

{}

Error Responses

Validation errors (invalid request body):

{
  "success": false,
  "result_text": "Validation failed, see 'result_data' -> 'errors'",
  "result_data": {
    "errors": [
      "'type' is required"
    ]
  }
}

Duplicate subscription (same type and url already exists):

{
  "success": false,
  "result_text": "A webhook subscription with this type and URL already exists",
  "result_data": {
    "id": "9f1c2a42baedb56c7e65b3eeaf1a8814"
  }
}

result_data.id is the ID of the existing subscription.

Not-found behaviour by method:

GET /hooks/{id}.json — returns null when the ID is not found.
DELETE /hooks/{id}.json — returns success even when the ID does not exist (idempotent).