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.
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: At least one of
email or linkedin_url 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
Required (at least one must be present)
| Field | Notes |
|---|
email | Contact’s email address |
linkedin_url | LinkedIn profile URL |
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:
{
"email": "[email protected]",
"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 |
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 |
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
