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)	Yes	Yes	The event type that triggers this subscription.
`url`	string (URI)	Yes	Yes	The destination URL that receives HTTP POST payloads.
`filter`	object	Yes	No	Optional key-value conditions that must match before delivery.

Note: All fields are immutable after creation. To change the type, url, or filter of an existing subscription, delete it 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: Yes — set at creation, cannot be updated.
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`	An email is sent to a contact.
`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.

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: Yes — set at creation, cannot be updated.
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 to acknowledge delivery. On non-2xx responses, Envoke will retry once after 10 minutes. If your endpoint returns HTTP 410 (Gone), the subscription is automatically removed.

`filter`

Type: Object
Read-only: Yes — set at creation, cannot be updated.
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.

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 integer 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, so a key that is not in the payload (for example campaign_id) never matches and every event is skipped.

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).

Full reference, OpenAPI description, and Postman collection: developers.envoke.com.