Inbound webhooks
Turn any form, landing page or tool that can post a webhook into contacts in your workspace, with field mapping and default tags.
An inbound webhook is a URL you give to a form, a landing page builder or any tool that can send a webhook. Each post creates the contact in your workspace, or updates it if the phone number already exists. Tags you set on the endpoint are added, so a tag-based automation can pick the contact up straight away.
Outbound events (a message was received, a send failed) are the other direction: see Webhooks.
Create an endpoint
In the app, open Developer → Inbound Webhooks and click New endpoint. You get a URL like this:
https://api.bluereacher.com/v1/receive-webhook?token=5f0c2b1e-8d7a-4c3e-9b21-6a4f0e7d9c18The token is created for you and cannot be chosen. Treat the URL like a password: anyone who has it can add contacts to your workspace. If it leaks, delete the endpoint and create a new one.
Each endpoint has:
| Setting | What it does |
|---|---|
| Name | Your label, shown in the endpoint list |
| Field mapping | Which incoming field fills which contact field, for example cell to Phone |
| Unmapped fields | Save them as custom fields (the default), add them to the contact's notes, or ignore them |
| Default tags | Added to every contact this endpoint creates or updates |
| Active | Paused endpoints refuse posts with 403 |
A workspace can hold 25 endpoints.
Send a post
Send a POST with JSON, form fields (application/x-www-form-urlencoded) or multipart/form-data. No API key is needed: the token in the URL is the credential. Browsers can post directly, because the endpoint answers cross-origin requests.
curl -X POST "https://api.bluereacher.com/v1/receive-webhook?token=YOUR_TOKEN" \
-H "content-type: application/json" \
-d '{"phone": "(415) 555-0100", "name": "Pat Lee", "email": "pat@example.com", "company": "Lee Roofing"}'A phone number is required. US numbers without a country code are read as +1.
Fields recognised without a mapping
| Contact field | Incoming names it picks up |
|---|---|
| Phone | phone, phone_number, mobile, cell, tel, telephone, number |
email, email_address | |
| First name | first_name, firstname, fname, given_name |
| Last name | last_name, lastname, lname, surname, family_name |
| Full name | name, full_name, contact_name (split into first and last) |
| Company | company, company_name, business, organization |
| Notes | notes, message, comments |
Names are matched without regard to case, spaces or dashes. Nested JSON is read too: {"lead": {"phone": "..."}} finds the phone. A mapping you set always wins over these defaults.
Responses
{ "success": true, "contact_id": "c_8f2a...", "is_new_contact": true }| Status | Meaning |
|---|---|
200 | Contact created or updated |
400 | Body is not JSON or form fields, or no phone number was found |
403 | The endpoint is paused |
404 | Unknown token |
405 | Not a POST |
413 | Body over 256 KB |
429 | Over 120 posts a minute on this endpoint; retry after a minute |
502 | The contact could not be saved; retry shortly |
Limits
- 120 posts a minute per endpoint.
- Bodies up to 256 KB.
- Up to 50 unmapped fields are saved per post as custom fields; the rest are dropped.
- Nested JSON is read up to five levels deep.
See every hit
Developer → Inbound Webhooks shows each endpoint's recent posts with the status, the time taken and the body received, so you can check a form is wired correctly without leaving the app.