Hooks API — Create

Use this endpoint to create a new webhook subscription in your account.

---

Endpoint

POST https://e1.envoke.com/v1/hooks.json

Authentication is via HTTP Basic Auth using your API ID and API Key. The request body must be JSON.

Returns HTTP 201 on success.

---

Request Body

Field	Type	Required	Description
type	string (enum)	Yes	The event type to subscribe to. See the full list of types below.
url	string (URI)	Yes	The destination URL that will receive HTTP POST payloads. Must start with http:// or https://.
filter	object	No	Key-value conditions that must match before delivery. Omit or pass {} to receive all events of the subscribed type.

Supported Event Types

Category	Type
Contact	new_contact, consent_change
Submission	submission, form_submission, preference_page_submission, api_submission, import_submission, ui_submission
Email Activity	email_send, email_open, email_click, email_autoresponder_send, email_bounce, email_spam_report, email_delivery
Lead	new_lead, passed_to_sales, lead_update, new_opportunity, new_sale

email_delivery is reserved for an upcoming release: you can subscribe to it now, but no events are delivered yet.

Filter Keys

The filter object accepts any key-value pairs that correspond to fields in the event payload. Common filter keys:

Event type(s)	Key	Description
Form events	form_id	Deliver only when the event originates from a specific form.
Email events	message_id	Deliver only when the event is associated with a specific email message, by its integer ID.
Email events	message_external_id	The same, by the message’s 32-character external ID. Use either key.

Filter keys must be fields of the delivered payload (see help_payloads.md). A key the payload does not contain, such as campaign_id, never matches, so every event is skipped.

Pass {} or omit filter entirely to receive all events with no filtering.

---

Response

On success, returns the newly created subscription ID with HTTP 201:

{"id": "9f1c2a42baedb56c7e65b3eeaf1a8814"}

id is the subscription ID. Store this to retrieve or delete the subscription later.

---

Validation Errors

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

Common validation errors:

Error	Cause
'type' is required	type was missing or blank.
Invalid webhook type: '{value}'	type is not one of the 20 supported values.
'url' is required	url was missing or blank.
'url' must start with http:// or https://	url does not begin with a valid scheme.
'filter' values must be scalar	A filter value was an array or object instead of a string, number, or boolean.

---

Duplicate Subscription Error

If a subscription with the same type and url already exists, the API returns HTTP 400:

{
  "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.

---

Examples

Subscribe to all form submissions from a specific form

A college wants to be notified in their admissions CRM every time a prospect submits the online inquiry form.

curl -X POST -ks \
  -u "$API_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "form_submission",
    "url": "https://crm.ridgeline.edu/webhooks/envoke/admissions",
    "filter": { "form_id": "abc123def456" }
  }' \
  "$BASE/v1/hooks.json"

Subscribe to email opens for a specific message

Track which students opened the fall course registration reminder to follow up with non-openers.

curl -X POST -ks \
  -u "$API_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "email_open",
    "url": "https://portal.ridgeline.edu/webhooks/engagement",
    "filter": { "message_id": "789" }
  }' \
  "$BASE/v1/hooks.json"

Subscribe to email clicks on an alumni giving message

Alert the giving office when an alumnus clicks the donation link in the annual appeal email. This example filters by the message’s external ID instead of its integer ID.

curl -X POST -ks \
  -u "$API_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "email_click",
    "url": "https://giving.ridgeline.edu/webhooks/envoke",
    "filter": { "message_external_id": "f5a3c1e9b7d5f3a1c9e7b5d3f1a9c7e5" }
  }' \
  "$BASE/v1/hooks.json"

Subscribe to hard bounces

Keep the CRM’s email addresses clean by flagging every contact whose address hard-bounces.

curl -X POST -ks \
  -u "$API_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "email_bounce",
    "url": "https://crm.ridgeline.edu/webhooks/envoke/bounces",
    "filter": { "bounce_type": "hard" }
  }' \
  "$BASE/v1/hooks.json"

Subscribe to spam reports

Flag contacts in the CRM as soon as they report an Envoke email as spam.

curl -X POST -ks \
  -u "$API_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "email_spam_report",
    "url": "https://crm.ridgeline.edu/webhooks/envoke/complaints"
  }' \
  "$BASE/v1/hooks.json"

Subscribe to all new contacts (no filter)

Sync every new contact to the student information system as soon as they are added.

curl -X POST -ks \
  -u "$API_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "new_contact",
    "url": "https://sis.ridgeline.edu/webhooks/contacts"
  }' \
  "$BASE/v1/hooks.json"

Subscribe to new leads

Notify the enrollment management team when a new lead is created.

curl -X POST -ks \
  -u "$API_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "new_lead",
    "url": "https://crm.ridgeline.edu/webhooks/leads"
  }' \
  "$BASE/v1/hooks.json"

---

Note: The curl examples above are formatted for readability. All requests must use properly encoded URLs.

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