# 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:

```json
{"id": "9f1c2a42baedb56c7e65b3eeaf1a8814"}
```

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

---

## Validation Errors

```json
{
  "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:

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

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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](https://developers.envoke.com).*