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

# Webhook documentation

## **Using Webhooks as a Data Source**

A webhook campaign uses an inbound POST request as its data source. Instead of uploading a CSV, you send leads to Artisan programmatically - from Zapier, Make.com, or any tool that can make HTTP requests.

Webhooks are available as a data source on **cold outbound**, **warm outbound**, and **cross-sell/upsell** campaigns. They let you send lead contact information alongside any custom fields from your external system, which can later also be used as personalization variables in your messaging.

**Why use webhooks:**

* Connect Artisan to any external system or workflow
* Pass custom fields (e.g. `plan_type`, `usage_arr`, `event_type`) directly into personalization
* Enable integrations we haven't built natively yet

***

## Setup

### Step 1 - Get your endpoint URL and API key

When you create a campaign and select **Webhook** as the data source, Artisan generates:

* A unique **Endpoint URL** (e.g. `https://api.artisan.co/v1/webhooks/campaign/{campaign_id}`)
* An **API Key** for authentication (e.g. `sk_live_...`)

Copy both. These are shown on the Targeting tab under **Webhook configuration**.

You can **Regenerate API key** at any time.

### Step 2 - Send a test payload

Use the provided **cURL snippet** to send a test payload.

**Note:** The "Check for new payloads" button shows you the last payload sent in the Preview sidedrawer. If you send new payloads, they get added to the old results.

### Step 3 - Map your fields

When you click **Check for new payloads** for the first time (or when new fields are detected in the webhook payload), the **Map webhook fields to Artisan fields** modal appears automatically.

* Each webhook field is listed on the left
* Map it to the corresponding Artisan field on the right (or leave unmapped)
* Checked rows are included; uncheck a row to exclude that field
* **Required:** `email` must be mapped

The mapping modal only re-opens if the fields in your payload change. If the same fields are sent again, it will not prompt you to remap.

After mapping, you can click **Edit field mapping** to change it at any time.

### Step 4 - Launch the campaign

Once your payload is validated and fields are mapped, continue through Sequence, Messaging, Senders, and Settings tabs, then **Launch**.

After launch, the targeting card updates to show live metrics (see Metrics section below).

***

## Using Webhook Fields as Personalizations

Any field included in your webhook payload (beyond the standard contact info fields) is made available for email personalization.

### Where they appear

When configuring **Deep** or **Agentic** personalization in the Messaging tab, a **Webhook** tab appears. All fields from your mapped payload are listed there and can be selected for use in emails.

For example, if your payload includes `plan_type: "Enterprise"` or `usage_arr: 12000`, those values will appear under the Webhook tab and if selected, Ava can reference them when personalizing outreach.

### How to use them

* Navigate to the **Messaging** tab of your campaign
* Under **Personalizations**, select **Deep** or **Agentic**
* Open the **Webhook** tab - all mapped webhook fields are listed here
* Enable the fields you want Ava to use when writing emails

Webhook fields are particularly powerful for cross-sell/upsell campaigns where you're passing real customer data like usage metrics, product events, or account attributes directly into the personalization layer.

***

## Required & Optional Fields

| Field   | Notes                   |
| ------- | ----------------------- |
| `email` | Contact's email address |

### Standard optional fields

| Field            | Description          |
| ---------------- | -------------------- |
| `first_name`     | Contact's first name |
| `last_name`      | Contact's last name  |
| `company_name`   | Company name         |
| `company_domain` | e.g. `acme.com`      |
| `title`          | Job title            |
| `phone`          | Phone number         |

### Custom fields

Any additional fields in your payload (e.g. `plan_type`, `usage_arr`, `event_type`) are captured and can be mapped as custom fields. These are also available as **personalization variables** in your messaging.

**Full example payload:**

```json theme={null}
{
  "email": "sarah@acme.com",
  "first_name": "Sarah",
  "last_name": "Chen",
  "company_name": "Acme Inc",
  "job_title": "VP of Engineering",
  "plan_type": "Enterprise",
  "usage_arr": 12000,
  "event_type": "usage_increase"
}
```

***

## Metrics: What the Card Shows

### Before launch (testing phase)

| Metric   | Meaning                                               |
| -------- | ----------------------------------------------------- |
| Received | Number of **records** (not payloads) received         |
| Valid    | Records that passed validation                        |
| Errors   | Records with missing required fields or format issues |

### After campaign launch

| Metric       | Meaning                               |
| ------------ | ------------------------------------- |
| Received     | Total records received                |
| Contacted    | Leads Ava has sent a message to       |
| Pending      | Queued leads waiting to be contacted  |
| Disqualified | Leads excluded by DNC or filter rules |
| Errors       | Records with validation errors        |

The errors are provided in a downloadable CSV of all errored records. After launch, this list accumulates as new errors come in.

***

## Preview Leads

Click the **eye icon** on the webhook card to open the **Preview leads** side drawer. This shows:

* **Leads tab:** All contacts received through this webhook (name, title)
* **Payload schema tab:** The last payload sent in JSON format

***

## API Response Codes

| Code  | Meaning                                                     |
| ----- | ----------------------------------------------------------- |
| `202` | Webhook received successfully                               |
| `400` | Invalid payload - missing required fields or malformed JSON |
| `401` | Invalid or missing API key                                  |
| `429` | Rate limit exceeded                                         |
| `500` | Server error                                                |

Artisan returns `200` immediately and processes leads asynchronously.

***

## Rate Limits

* 10 requests per minute per campaign webhook

***

## Common Integrations

Webhooks work with any tool that can make HTTP POST requests:

* **Zapier** - trigger on any Zap event
* **HubSpot** - workflow action to send contacts
* **BigQuery / custom backend** - send on usage events or scoring
* **Make (formerly Integromat)** - HTTP module
* **Postman / cURL** - for testing