> ## Documentation Index
> Fetch the complete documentation index at: https://docs.politicalcomms.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Inbound hook

> Add one recipient to a triggered text project or email campaign from Zapier, Make, n8n, or anything that can send a POST request, with no API key.

Every webhook on the other pages of this section is **outbound**: we send events to you. The inbound hook runs the other way. A triggered text project or email campaign can give you a URL, and any tool that can `POST` to it adds one recipient. That makes a CRM, a form, or a no-code tool a trigger without writing code.

Use it with a project or campaign whose trigger source is an API call or webhook. For how triggered sends behave, see [Triggered texts and emails](https://docs.politicalcomms.com/help/triggered-sends.md).

## Get the hook URL

There are two places to get it, and both give you the same three values:

* **In the dashboard.** Open the report page of a triggered project or campaign whose trigger is **An API call or webhook**, and choose **Generate webhook URL**. The page shows the webhook URL, and under it the address and secret for tools that can set headers.
* **Over the API.** Call `POST /v1/projects/{id}/hook` for a text project or `POST /v1/email/campaigns/{id}/hook` for an email campaign.

The values are shown once, at the moment they are generated. The response below is an example with made-up values; yours will have your own project or campaign id and a 64-character secret.

```json theme={null}
{
  "success": true,
  "data": {
    "hook_url": "https://api.politicalcomms.com/webhooks/trigger/text/8a3f5c7e-2d91-4b64-ae08-6f1c9d3e7b52/EXAMPLE_SECRET_SHOWN_ONCE",
    "endpoint_url": "https://api.politicalcomms.com/webhooks/trigger/text/8a3f5c7e-2d91-4b64-ae08-6f1c9d3e7b52",
    "secret": "EXAMPLE_SECRET_SHOWN_ONCE"
  }
}
```

There are two ways to call the hook, and both use the same secret:

* **`hook_url`** has the secret in the address. Use it in tools that can only be given a URL.
* **`endpoint_url`** has no secret in it. Send the `secret` in an `X-Hook-Secret` header. Prefer this when your tool can set headers: a URL can end up in proxy logs and browser history, and a header does not.

Either one is the whole credential: anyone who has it can add recipients. Store it like a secret.

**Your own domain.** If your organization has its own domain, both `hook_url` and `endpoint_url` are built on it, for example `https://go.yourdomain.org/webhooks/trigger/text/...`. The domain is chosen in this order: the tracking domain the project or campaign uses for its own links; your organization's only tracking domain; your organization's only dashboard domain, or its parent organization's. When there are several candidates and none is chosen on the item, or there is no domain at all, both are on `api.politicalcomms.com`. A URL on either host works the same way.

> [!WARNING]
>
> The URL is shown only when it is created. Creating a new one **rotates** it: the previous URL stops working at once and answers `404`. Rotate when a URL leaks or when a person who had it leaves, then paste the new URL into your tools.

## Send a recipient

`POST` the hook URL (or the endpoint URL with the `X-Hook-Secret` header) with a JSON or form body. No `X-API-Key` header and no signature are needed.

| Field | Used for | Notes |
| - | - | - |
| `phone_number` (or `phone`) | Text projects | Required. A US number. Numbers in other countries, including Canada, are refused, because the overnight hold depends on a US area code. |
| `email` | Email campaigns | Required. |
| `occurrence_id` | Both | Optional, up to 128 characters. Your id for the event, so a retry of the same event is a no-op. |
| Any other top-level key | Both | Becomes a field on the recipient. Strings, numbers and booleans only; nested objects and arrays are ignored. |

Fields are merge tags in your message (`{first_name}`), are kept on the recipient, and appear in reports, exports and the `contact.custom_fields` of your outbound webhooks.

```bash theme={null}
curl -X POST "https://api.politicalcomms.com/webhooks/trigger/text/8a3f5c7e-2d91-4b64-ae08-6f1c9d3e7b52/EXAMPLE_SECRET_SHOWN_ONCE" \
  -H "Content-Type: application/json" \
  -d '{"phone_number": "+12025550141", "first_name": "Ada", "amount": 25, "occurrence_id": "evt_123"}'
```

## Answers

The hook adds the recipient before it answers, so a `2xx` means the person was actually entered. A tool that shows you only the status code can trust it.

| Status | Meaning |
| - | - |
| `202` | Queued. `send_at` is when the message will send, after the trigger's delay and, for a text, any overnight hold. |
| `200` | Not added because this person or this `occurrence_id` was already entered. `reason` is `duplicate` or `already_entered`; a person is sent a triggered project or campaign once. This is the normal answer to a retry. |
| `409` | Not accepting. The project or campaign is paused, never started, or ended, or this person has opted out (suppressed, for email). A paused item refuses recipients; it does not queue them. |
| `422` | The phone number or email is missing, or cannot be sent to: not a US number, an unusable address, or an email address that has unsubscribed or is suppressed. |
| `404` | The URL is unknown or was rotated. |
| `429` | More than 600 requests a minute to the same hook. |

A `202` or `200` answer has this shape:

```json theme={null}
{ "success": true, "data": { "status": "queued", "send_at": "2026-11-13T14:00:00.000Z" } }
```

## Zapier and Make

You do not need a published app: the generic webhook step in each tool works with the URL.

> [tab] Zapier
>
> 1. Choose your trigger, for example a new row in Google Sheets or a new contact in your CRM.
> 2. Add the action **Webhooks by Zapier**, event **POST**.
> 3. Set **URL** to the hook URL and **Payload Type** to `json`.
> 4. Under **Data**, add `phone_number` (or `email`) and map it from your trigger. Add one line per field you want in the message, such as `first_name`. Add `occurrence_id` mapped to a unique id from the trigger, such as the row id.
> 5. Test the step. A `202` with `queued` means the person was added.

> [tab] Make
>
> 1. Add your trigger module, for example **Watch rows** or a CRM module.
> 2. Add **HTTP > Make a request**. Set **URL** to the hook URL and **Method** to `POST`.
> 3. Set **Body type** to `Raw`, **Content type** to `JSON (application/json)`, and the request content to a JSON body like the one above, mapping values from the trigger module.
> 4. Turn on **Parse response** and run once. A `202` or `200` means the hook accepted the call.

In either tool, send an `occurrence_id` so that a replayed run does not send twice.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.