Hooks API — Webhook Payloads
This article describes the payload Envoke delivers to your endpoint for each event type.
Delivery Format
Section titled “Delivery Format”Envoke delivers webhook payloads as HTTP POST requests to your registered URL. The request body is always a JSON array, even when a single event is delivered.
POST https://your-endpoint.example.com/webhookContent-Type: application/json
[ { ... event object ... } ]Email activity events (email_send, email_open, email_click) may be batched — a single POST can contain multiple events from the same send or activity processing run. email_bounce events are batched when the failure happens while Envoke is sending (all such failures from one sending run arrive in one POST); bounces reported later by the recipient’s mail server arrive one object per request. email_spam_report events deliver one object per request. email_delivery events, when they become available, will be batched. All other event types deliver exactly one object per request. Always read the body as an array.
On a non-2xx response, Envoke retries once after 10 minutes. If your endpoint returns HTTP 410, the subscription is automatically removed.
Contact Events
Section titled “Contact Events”new_contact
Section titled “new_contact”Fires when a new contact is added to your account by any means (form, import, API, or manual entry). The payload is the full contact record — the same object the Contacts API returns for that contact.
Payload fields:
| Field | Type | Description |
|---|---|---|
id |
integer | Envoke internal contact ID. |
external_id |
string | Envoke-generated 32-character hex identifier. |
remote_id |
string | Your system’s identifier for this contact, if set. Empty string if not set. |
date_created |
string | Date and time the contact was created (YYYY-MM-DD HH:MM:SS). |
first_name |
string | |
last_name |
string | |
title |
string | Job title or academic title. |
email |
string | |
company |
string | |
phone |
string | |
address_1 |
string | |
address_2 |
string | |
city |
string | |
province |
string | Province or state. |
postal_code |
string | |
country |
string | Two-letter ISO country code. |
website |
string | |
language |
string | Preferred language code (e.g. "en", "fr"). |
feedback |
string | Internal notes field. |
consent_status |
string | Current consent type name (e.g. "Express", "Implied", "No Consent"). |
consent_description |
string | Description of how consent was obtained. |
consent_effective_date |
string | When the current consent became effective. |
consent_expiry |
string | When the consent expires, if applicable. Empty string if no expiry. |
interests |
array | Contact’s interest group memberships. |
custom_fields |
array | Custom field values. |
autoresponders |
array | Autoresponder assignments. |
timestamp |
integer | Unix timestamp of when the contact was created. |
Example scenario: Northfield University subscribes to new_contact to sync incoming contacts to their student information system as soon as they appear in Envoke.
Example payload:
[ { "id": 84291, "external_id": "3f8a1c042d7e9b56a0e14c3d8f2b5a91", "remote_id": "NF-STU-2024-00847", "date_created": "2024-09-03 08:41:22", "timestamp": 1725352882, "first_name": "Miguel", "last_name": "Torres", "title": "", "email": "m.torres@students.northfield.edu", "company": "Northfield University", "phone": "555-204-3817", "address_1": "14 Birchwood Avenue", "address_2": "", "city": "Northfield", "province": "ON", "postal_code": "N2R 4K7", "country": "CA", "website": "", "language": "en", "feedback": "", "consent_status": "Express", "consent_description": "Submitted online enrollment inquiry form on September 3, 2024.", "consent_effective_date": "2024-09-03 08:41:22", "consent_expiry": "", "interests": [ { "id": 12, "name": "Graduate Programs", "state": "Set" } ], "custom_fields": { "student_type": "Graduate" }, "autoresponders": [], "timestamp": 1725352882 }]consent_change
Section titled “consent_change”Fires when a contact’s consent status changes — for example, when they unsubscribe, re-subscribe, or their consent type is updated. The payload contains all the same fields as new_contact plus two additional fields that describe the reason for the change.
Additional fields:
| Field | Type | Description |
|---|---|---|
unsubscribe_reason |
string | The unsubscribe reason category selected by the contact. Empty string if not set or if consent improved. |
unsubscribe_reason_detail |
string | Free-text detail provided by the contact at unsubscribe. Empty string if not provided. |
Example scenario: Northfield University subscribes to consent_change to update opt-out status in their alumni CRM when a contact unsubscribes.
Example payload:
[ { "id": 61048, "external_id": "9c4e2b871f3a5d0e6b82c7a14f3d9e02", "remote_id": "ALM-2008-4421", "date_created": "2021-06-14 10:22:09", "first_name": "Helen", "last_name": "Webb", "title": "Associate Professor", "email": "h.webb@northfield.edu", "company": "Northfield University — Faculty of Arts", "phone": "", "address_1": "", "address_2": "", "city": "", "province": "", "postal_code": "", "country": "CA", "website": "", "language": "en", "feedback": "", "consent_status": "No Consent", "consent_description": "", "consent_effective_date": "2025-02-18 14:07:33", "consent_expiry": "", "interests": [], "custom_fields": {}, "autoresponders": [], "timestamp": 1739884053, "unsubscribe_reason": "Too frequent", "unsubscribe_reason_detail": "I receive too many emails from this list." }]Submission Events
Section titled “Submission Events”All submission event types share the same payload structure. The submission_type field identifies the origin:
| Subscription type | submission_type value |
|---|---|
form_submission |
"form_submission" |
preference_page_submission |
"preference_page_submission" |
api_submission |
"api_submission" |
import_submission |
"import_submission" |
ui_submission |
"ui_submission" |
submission |
One of the five values above |
The generic submission type delivers the same payload as whichever specific type triggered the event. Subscribing to submission is equivalent to subscribing to all five specific types at once.
Common payload fields:
| Field | Type | Description |
|---|---|---|
id |
string | Unique identifier for this submission event. |
contact_id |
integer | Envoke internal contact ID. |
contact_external_id |
string | Envoke-generated 32-character hex identifier for the contact. |
contact_remote_id |
string | Your system’s identifier for this contact, if set. Empty string if not set. |
contact_created |
boolean | true if this submission created the contact; false if it updated an existing one. |
submission_type |
string | The submission origin. See the table above. |
submission_time |
string | Date and time of the submission (YYYY-MM-DD HH:MM:SS). |
timestamp |
integer | Unix timestamp of the submission. |
first_name |
string | |
last_name |
string | |
title |
string | |
email |
string | |
company |
string | |
phone |
string | |
address_1 |
string | |
address_2 |
string | |
city |
string | |
province |
string | |
postal_code |
string | |
country |
string | |
website |
string | |
language |
string | |
feedback |
string | |
consent_status |
string | |
consent_description |
string | |
consent_effective_date |
string | |
consent_expiry |
string | |
visitor_id |
string | Visitor tracking ID. Empty string when not applicable (e.g. imports, manual adds). |
visit_id |
string | Visit tracking ID. Empty string when not applicable. |
pageview_id |
string | Pageview tracking ID. Empty string when not applicable. |
Additional fields for form_submission only:
| Field | Type | Description |
|---|---|---|
form_id |
string | The ID of the form that was submitted. |
form_name |
string | The name of the form in Envoke. |
form_url |
string | The URL of the page where the form was submitted. |
form_submission
Section titled “form_submission”Example scenario: Northfield University subscribes to form_submission filtered by form_id to push prospective student inquiries from the graduate admissions form directly into their Slate CRM.
[ { "id": "5e8f2a1d3c0b4e9a7f6d2c4b1a8e5d03", "contact_id": 92714, "contact_external_id": "a7d3e1f0b2c4e6a8d0f2b4c6e8a0d2f4", "contact_remote_id": "", "contact_created": true, "submission_type": "form_submission", "submission_time": "2025-01-15 11:23:47", "timestamp": 1736940227, "first_name": "Priya", "last_name": "Sharma", "title": "", "email": "priya.sharma@gmail.com", "company": "", "phone": "555-318-0042", "address_1": "", "address_2": "", "city": "Hamilton", "province": "ON", "postal_code": "L8P 1A1", "country": "CA", "website": "", "language": "en", "feedback": "", "consent_status": "Express", "consent_description": "Checked the consent checkbox on the Graduate Admissions Inquiry form.", "consent_effective_date": "2025-01-15 11:23:47", "consent_expiry": "", "form_id": "f3b2e1a0d4c5b6a7e8f9d0c1b2a3e4f5", "form_name": "Graduate Admissions Inquiry", "form_url": "https://www.northfield.edu/graduate/apply", "visitor_id": "67a1b2c3d4e5f6a7b8c9d0e1", "visit_id": "67a1b2c3d4e5f6a7b8c9d0e2", "pageview_id": "67a1b2c3d4e5f6a7b8c9d0e3" }]preference_page_submission
Section titled “preference_page_submission”Example scenario: Northfield University subscribes to preference_page_submission to update their alumni database when graduates adjust their communication preferences.
[ { "id": "2c4e6a8b0d2f4a6c8e0a2c4e6a8b0d2f", "contact_id": 55830, "contact_external_id": "b1d3f5a7c9e1b3d5f7a9c1e3b5d7f9a1", "contact_remote_id": "ALM-2015-8803", "contact_created": false, "submission_type": "preference_page_submission", "submission_time": "2025-03-22 16:04:11", "timestamp": 1742659451, "first_name": "James", "last_name": "Okwu", "title": "", "email": "james.okwu@outlook.com", "company": "Westridge Financial Group", "phone": "", "address_1": "", "address_2": "", "city": "Toronto", "province": "ON", "postal_code": "M5V 2T6", "country": "CA", "website": "", "language": "en", "feedback": "", "consent_status": "Express", "consent_description": "Re-confirmed consent on Alumni Preference Page.", "consent_effective_date": "2025-03-22 16:04:11", "consent_expiry": "", "visitor_id": "68b2c3d4e5f6a7b8c9d0e1f2", "visit_id": "68b2c3d4e5f6a7b8c9d0e1f3", "pageview_id": "68b2c3d4e5f6a7b8c9d0e1f4" }]api_submission
Section titled “api_submission”Example scenario: Northfield University’s student information system (SIS) syncs newly enrolled students to Envoke via the API. The api_submission hook confirms each sync in their enrollment management platform.
[ { "id": "1a3c5e7b9d1f3a5c7e9b1d3f5a7c9e1b", "contact_id": 103445, "contact_external_id": "c2e4a6b8d0f2c4e6a8b0d2f4c6e8a0b2", "contact_remote_id": "SIS-2025-1142", "contact_created": true, "submission_type": "api_submission", "submission_time": "2025-09-02 07:15:30", "timestamp": 1756696530, "first_name": "Lucas", "last_name": "Brennan", "title": "", "email": "l.brennan@students.northfield.edu", "company": "Northfield University", "phone": "", "address_1": "", "address_2": "", "city": "", "province": "", "postal_code": "", "country": "CA", "website": "", "language": "en", "feedback": "", "consent_status": "Express", "consent_description": "Express consent provided at enrollment.", "consent_effective_date": "2025-09-02 07:15:30", "consent_expiry": "", "visitor_id": "", "visit_id": "", "pageview_id": "" }]import_submission
Section titled “import_submission”Example scenario: Northfield University imports an updated alumni mailing list each year from a spreadsheet. The import_submission hook notifies their alumni engagement platform of each record.
[ { "id": "4d6f8b2a0c4e6d8f2a4c6e8b0d2f4a6c", "contact_id": 48902, "contact_external_id": "d0e2c4a6b8f0d2e4c6a8b0f2d4e6c8a0", "contact_remote_id": "ALM-1998-0044", "contact_created": false, "submission_type": "import_submission", "submission_time": "2025-02-10 09:00:14", "timestamp": 1739181614, "first_name": "Diane", "last_name": "Kowalski", "title": "Director of Operations", "email": "dkowalski@northviewlogistics.com", "company": "Northview Logistics", "phone": "555-492-1780", "address_1": "88 Industrial Parkway", "address_2": "Suite 200", "city": "Kitchener", "province": "ON", "postal_code": "N2H 3R4", "country": "CA", "website": "https://www.northviewlogistics.com", "language": "en", "feedback": "", "consent_status": "Implied", "consent_description": "Alumni — implied consent under CASL.", "consent_effective_date": "2025-02-10 09:00:14", "consent_expiry": "2027-02-10 09:00:14", "visitor_id": "", "visit_id": "", "pageview_id": "" }]Additional fields for ui_submission only:
| Field | Type | Description |
|---|---|---|
is_bulk_update |
boolean | true if the contact was added or updated as part of a bulk manual operation; false if added individually. |
ui_submission
Section titled “ui_submission”Example scenario: A staff member in the Alumni Relations office manually adds a community partner who called in to request information about the Distinguished Alumni Speaker Series.
[ { "id": "9e1b3d5f7a9c1e3b5d7f9a1c3e5b7d9f", "contact_id": 71256, "contact_external_id": "e8a0b2d4f6e8a0b2d4f6c8e0a2b4d6f8", "contact_remote_id": "", "contact_created": true, "submission_type": "ui_submission", "submission_time": "2025-04-07 14:52:00", "timestamp": 1744037520, "first_name": "Robert", "last_name": "Nakamura", "title": "Executive Director", "email": "r.nakamura@northfieldarts.org", "company": "Northfield Arts Foundation", "phone": "555-783-2200", "address_1": "31 Gallery Row", "address_2": "", "city": "Northfield", "province": "ON", "postal_code": "N2R 1P3", "country": "CA", "website": "https://www.northfieldarts.org", "language": "en", "feedback": "Called requesting information about the Distinguished Alumni Speaker Series.", "consent_status": "Express", "consent_description": "Verbal consent given over phone on April 7, 2025.", "consent_effective_date": "2025-04-07 14:52:00", "consent_expiry": "", "visitor_id": "", "visit_id": "", "pageview_id": "", "is_bulk_update": false }]Email Activity Events
Section titled “Email Activity Events”All email activity event types share a common set of fields.
Common fields:
| Field | Type | Description |
|---|---|---|
activity_type |
string | The event type: "email_send", "email_open", "email_click", "email_autoresponder_send", "email_bounce", "email_spam_report", or "email_delivery". |
timestamp |
integer | Unix timestamp when the event occurred. |
message_id |
integer | Envoke internal ID of the email campaign. |
message_external_id |
string | Envoke-generated 32-character hex identifier for the campaign. |
message_name |
string | The internal name of the campaign in Envoke. |
message_subject |
string | The email subject line. May contain unresolved merge field tokens. |
sender |
string | The sender identity configured on the campaign. Name and address (Name <sender@example.com>). |
contact_id |
integer | Envoke internal contact ID. |
contact_external_id |
string | Envoke-generated 32-character hex identifier for the contact. |
contact_email |
string | The email address the message was sent to. |
contact_remote_id |
string or null | Your system’s identifier for this contact. null if not set. |
email_send
Section titled “email_send”Fires when an email is sent to a contact. Send events are batched — a single POST to your endpoint will typically contain multiple objects, one per recipient.
Example scenario: Northfield University subscribes to email_send filtered by message_id to log each delivery of the monthly alumni newsletter in their engagement platform.
[ { "activity_type": "email_send", "timestamp": 1715432791, "message_id": 2048, "message_external_id": "7e4a1f2c9b3d5e0a8f6c2b4d9e1a3f5c", "message_name": "Alumni Newsletter — May 2025", "message_subject": "What's happening at Northfield this spring", "sender": "Northfield Alumni Relations <alumni@northfield.edu>", "contact_id": 55830, "contact_external_id": "b1d3f5a7c9e1b3d5f7a9c1e3b5d7f9a1", "contact_email": "james.okwu@outlook.com", "contact_remote_id": "ALM-2015-8803" }, { "activity_type": "email_send", "timestamp": 1715432804, "message_id": 2048, "message_external_id": "7e4a1f2c9b3d5e0a8f6c2b4d9e1a3f5c", "message_name": "Alumni Newsletter — May 2025", "message_subject": "What's happening at Northfield this spring", "sender": "Northfield Alumni Relations <alumni@northfield.edu>", "contact_id": 48902, "contact_external_id": "d0e2c4a6b8f0d2e4c6a8b0f2d4e6c8a0", "contact_email": "dkowalski@northviewlogistics.com", "contact_remote_id": "ALM-1998-0044" }]email_open
Section titled “email_open”Fires when a contact opens an email. Open events are batched — a single POST may contain opens from multiple contacts processed in the same activity run.
Example scenario: Northfield University tracks opens of the course registration deadline reminder to identify students who may need a follow-up call.
[ { "activity_type": "email_open", "timestamp": 1715518340, "message_id": 2051, "message_external_id": "3c7b9e2f1a4d6c8a0e2b4f6d8a0c2e4b", "message_name": "Fall Registration Deadline Reminder", "message_subject": "Action required: course registration closes Friday", "sender": "Northfield Registrar <registrar@northfield.edu>", "contact_id": 84291, "contact_external_id": "3f8a1c042d7e9b56a0e14c3d8f2b5a91", "contact_email": "m.torres@students.northfield.edu", "contact_remote_id": "NF-STU-2024-00847" }]email_click
Section titled “email_click”Fires when a contact clicks a tracked link in an email. Click events are batched. Includes the URL and anchor text of the clicked link in addition to the common fields.
Additional fields:
| Field | Type | Description |
|---|---|---|
link_url |
string or null | The destination URL of the clicked link. |
link_text |
string or null | The anchor text of the clicked link. |
Example scenario: Northfield University’s development office subscribes to email_click filtered by message_id to alert gift officers the moment an alumnus clicks the donation button in the annual giving appeal.
[ { "activity_type": "email_click", "timestamp": 1716047220, "message_id": 2063, "message_external_id": "f5a3c1e9b7d5f3a1c9e7b5d3f1a9c7e5", "message_name": "2025 Annual Giving Appeal", "message_subject": "Your gift helps the next generation of Northfield students", "sender": "Northfield Annual Fund <giving@northfield.edu>", "contact_id": 55830, "contact_external_id": "b1d3f5a7c9e1b3d5f7a9c1e3b5d7f9a1", "contact_email": "james.okwu@outlook.com", "contact_remote_id": "ALM-2015-8803", "link_url": "https://give.northfield.edu/annual-fund?utm_source=envoke", "link_text": "Make a gift today" }]email_autoresponder_send
Section titled “email_autoresponder_send”Fires when an autoresponder email is sent to a contact. Includes the autoresponder ID and name in addition to the common fields.
Additional fields:
| Field | Type | Description |
|---|---|---|
autoresponder_id |
integer | Envoke internal ID of the autoresponder. |
autoresponder_name |
string | The name of the autoresponder in Envoke. |
Example scenario: Northfield University sends a welcome sequence to newly enrolled students. They subscribe to email_autoresponder_send to log each autoresponder delivery in their student success platform.
[ { "activity_type": "email_autoresponder_send", "timestamp": 1725282930, "message_id": 1984, "message_external_id": "a2e4c6b8d0f2a4c6e8b0d2f4a6c8e0b2", "message_name": "Welcome to Northfield — Message 1", "message_subject": "Welcome to Northfield University", "sender": "Northfield Admissions <welcome@northfield.edu>", "contact_id": 103445, "contact_external_id": "c2e4a6b8d0f2c4e6a8b0d2f4c6e8a0b2", "contact_email": "l.brennan@students.northfield.edu", "contact_remote_id": "SIS-2025-1142", "autoresponder_id": 47, "autoresponder_name": "New Student Welcome Sequence" }]email_bounce
Section titled “email_bounce”Fires when an email to a contact fails: the recipient’s mail server bounces it, or Envoke’s sending server cannot hand it over. Temporary deferrals, where the recipient’s server asks Envoke to try again later, do not fire this event because the message may still be delivered. Includes the kind of bounce, the reason, and whether Envoke has stopped sending to the contact, in addition to the common fields.
Additional fields:
| Field | Type | Description |
|---|---|---|
bounce_type |
string | The kind of failure. "hard": the recipient’s server permanently refused the message, for example because the address does not exist. "soft": the recipient’s server returned a failure that may not be permanent, for example a full mailbox. "smtp_error": Envoke’s sending server could not hand the message to the recipient’s server. "invalid_address": the address was refused as invalid at send time. "rejected": the message was rejected before delivery. |
bounce_reason |
string | The diagnostic text reported for the failure, up to 255 characters, starting at the SMTP reply (for example 550 5.1.1 ...). Raw SMTP transcript details are removed. May be an empty string. |
contact_blocked |
boolean | true when, after this failure, the contact’s fail score is at or above your account’s limit, so Envoke no longer sends email to this contact. It stays true for any later bounce while the contact remains over the limit. |
Example scenario: Northfield University subscribes to email_bounce filtered by bounce_type hard so their CRM can flag alumni whose email addresses no longer work.
[ { "activity_type": "email_bounce", "timestamp": 1761148800, "message_id": 2048, "message_external_id": "7e4a1f2c9b3d5e0a8f6c2b4d9e1a3f5c", "message_name": "Alumni Newsletter — May 2025", "message_subject": "What's happening at Northfield this spring", "sender": "Northfield Alumni Relations <alumni@northfield.edu>", "contact_id": 55830, "contact_external_id": "b1d3f5a7c9e1b3d5f7a9c1e3b5d7f9a1", "contact_email": "james.okwu@outlook.com", "contact_remote_id": "ALM-2015-8803", "bounce_type": "hard", "bounce_reason": "550 5.1.1 The email account that you tried to reach does not exist", "contact_blocked": true }]email_spam_report
Section titled “email_spam_report”Fires when a contact reports an email as spam. A consent_change event also fires for the same report; email_spam_report adds the message the contact reported. When a mailbox provider reports a complaint, only the contact the email was sent to fires this event, even if other contacts in your account share the same email address. Includes the source of the report in addition to the common fields.
Additional fields:
| Field | Type | Description |
|---|---|---|
source |
string | Where the report came from. "feedback_loop": the contact’s mailbox provider forwarded the complaint, for example after the contact pressed “Report spam” in their inbox. "envoke": the contact chose the report-spam option on the Envoke preference page. |
Example scenario: Northfield University subscribes to email_spam_report so their advancement team can review which messages draw complaints and suppress those alumni from future appeals.
[ { "activity_type": "email_spam_report", "timestamp": 1761148800, "message_id": 2048, "message_external_id": "7e4a1f2c9b3d5e0a8f6c2b4d9e1a3f5c", "message_name": "Alumni Newsletter — May 2025", "message_subject": "What's happening at Northfield this spring", "sender": "Northfield Alumni Relations <alumni@northfield.edu>", "contact_id": 48902, "contact_external_id": "d0e2c4a6b8f0d2e4c6a8b0f2d4e6c8a0", "contact_email": "dkowalski@northviewlogistics.com", "contact_remote_id": "ALM-1998-0044", "source": "feedback_loop" }]email_delivery
Section titled “email_delivery”Coming soon:
email_deliveryis reserved for an upcoming release. You can create a subscription for it now, but no events are delivered yet.
Fires when the recipient’s mail server accepts an email. Delivery events will be batched — a single POST may contain deliveries for many contacts. Includes the accepting server and its response in addition to the common fields.
Additional fields:
| Field | Type | Description |
|---|---|---|
relay |
string | The host name of the mail server that accepted the message, for example mx.example.com. |
response |
string or null | The accepting server’s response, up to 255 characters. null if not available. |
For this event, timestamp is the time the recipient’s server accepted the message.
Example scenario: Northfield University subscribes to email_delivery to record proof of delivery for each tuition deadline notice sent to students.
[ { "activity_type": "email_delivery", "timestamp": 1761148803, "message_id": 2051, "message_external_id": "3c7b9e2f1a4d6c8a0e2b4f6d8a0c2e4b", "message_name": "Fall Registration Deadline Reminder", "message_subject": "Action required: course registration closes Friday", "sender": "Northfield Registrar <registrar@northfield.edu>", "contact_id": 84291, "contact_external_id": "3f8a1c042d7e9b56a0e14c3d8f2b5a91", "contact_email": "m.torres@students.northfield.edu", "contact_remote_id": "NF-STU-2024-00847", "relay": "mx.example.com", "response": "250 2.0.0 OK 1761148803 x.y - gsmtp" }]Full reference, OpenAPI description, and Postman collection: developers.envoke.com.

