Hooks API — Create | Envoke Help Center

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`
Lead	`new_lead`, `passed_to_sales`, `lead_update`, `new_opportunity`, `new_sale`

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	`campaign_id`	Deliver only when the event is associated with a specific email campaign.

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 17 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 campaign

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": { "campaign_id": "789" }   }' \   "$BASE/v1/hooks.json"

Subscribe to email clicks on an alumni giving campaign

Alert the giving office when an alumnus clicks the donation link in the annual appeal email.

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": { "campaign_id": "1024" }   }' \   "$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.

For code examples and interactive testing, visit api.envoke.com.