> For the complete documentation index, see [llms.txt](https://humanic.gitbook.io/humanic/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://humanic.gitbook.io/humanic/getting-started-with-humanic/connecting-your-data/connect-using-a-webhook.md).

# Connect using a WebHook

POST JSON contacts and events to Humanic from any tool or backend.

Humanic's generic webhook accepts an HTTP `POST` with a JSON body. If your product, database, or automation tool can make an HTTP call, it can send data to Humanic — no native integration required.

Use this for custom backends, internal dashboards, Zapier, Make, n8n, form builders, CRMs, or any in-house system.

If you use PostHog, Shopify, or RudderStack, those have dedicated guides and their own webhook URLs.

***

### How it works

```
Your system / tool / product backend
         ↓
HTTP POST to Humanic webhook URL
  (JSON payload with email + optional event data)
         ↓
Humanic matches or creates a contact
         ↓
Campaigns can fire from the mapped event name
         ↓
Email sends from your configured domain
```

***

### Step 1 — Get your webhook URL

1. In Humanic, go to **Integrations → Webhooks**
2. Create a webhook (contact upsert or event) and copy the URL

It looks like:

```
https://prod.humanic.ai/api/webhooks/integrations/[token]
```

Keep this URL private. Anyone with it can POST data to your workspace. If it is exposed, rotate it from Integrations.

***

### Step 2 — Choose a payload shape

You can remap JSON paths in the webhook wizard. The defaults below match what Humanic shows as the sample payload.

#### Contact upsert (create / update a contact)

Default mapping: `email` and `name` at the top level. Extra keys are stored as contact data.

```json
{
  "email": "email@example.com",
  "name": "User Name",
  "data_field_1": "value_1",
  "data_field_2": "value_2"
}
```

`email` is required. Without an event mapping, this updates the contact list (default event name is `webhook`).

#### Event (contact + named event)

Default mapping: email/name under `user_data`, event name at `event_name`.

```json
{
  "user_id": "user_id_1",
  "event_name": "event_name_1",
  "user_data": {
    "email": "email@example.com",
    "name": "User Name",
    "data_field_1": "value_1",
    "data_field_2": "value_2"
  },
  "event_data": {
    "data_field_1": "value_1",
    "data_field_2": "value_2"
  }
}
```

| Field                   | Required           | Description                             |
| ----------------------- | ------------------ | --------------------------------------- |
| email (or mapped path)  | Yes                | Used to match or create a contact       |
| event\_name             | For event webhooks | Campaign trigger name (case-sensitive)  |
| user\_id                | Optional           | Your internal user id                   |
| user\_data / extra keys | Optional           | Contact fields / personalisation tokens |
| event\_data             | Optional           | Event-specific properties               |

***

### Step 3 — Send a test call

```bash
curl -X POST https://prod.humanic.ai/api/webhooks/integrations/[token] \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_id_1",
    "event_name": "user_signed_up",
    "user_data": {
      "email": "test@yourdomain.com",
      "name": "Test User"
    },
    "event_data": {
      "plan": "free"
    }
  }'
```

A successful call returns `HTTP 200`. Confirm the event in **Integrations** on that webhook.

***

### Sending from common tools

#### Zapier

Add a **Webhooks by Zapier** action. Method **POST**, paste the Humanic URL, `Content-Type: application/json`, and map your JSON body.

#### Make

Add **HTTP → Make a Request**. Method `POST`, body type `Raw` with `Content-Type: application/json`.

#### n8n

Use the **HTTP Request** node. Method `POST`, body content type `JSON`. See also the [n8n](/humanic/getting-started-with-humanic/connecting-your-data/n8n.md) page.

#### Your own backend (Node.js)

```javascript
await fetch('https://prod.humanic.ai/api/webhooks/integrations/[token]', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    user_id: user.id,
    event_name: 'subscription_upgraded',
    user_data: { email: user.email, name: user.name },
    event_data: { plan: newPlan }
  })
});
```

***

### Best practices

* Always include an email (or a mapped path that resolves to one). Without it Humanic cannot attach the event to a contact.
* Use consistent event names (`snake_case` is the usual convention). Names are case-sensitive.
* Only send fields you will use in email copy or targeting.
* One event per request. For bulk historical imports, use CSV instead.
* The URL is the secret. Do not commit it to a public repo.

***

### Troubleshooting

**Events aren't appearing** — Confirm `Content-Type: application/json` and that you are posting to the URL shown in Integrations (not an old `api.humanic.ai` URL).

**Contact is created but no email sends** — The mapped event name must match a campaign trigger, and your sending domain must be verified.

**Fields missing in emails** — Token names must match the JSON keys you send (or the paths you mapped in the wizard).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://humanic.gitbook.io/humanic/getting-started-with-humanic/connecting-your-data/connect-using-a-webhook.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.