---
title: "REST Webhook (Custom CRM) - Auto-Respond Docs"
description: "Connect any CRM or custom system to Auto-Respond by having it POST lead events to a URL you control. Use this when your CRM isn't in the supported list."
source: https://auto-respond.com/docs/integrations/rest-webhook/
last_updated: 2026-07-03
---

![REST Webhook (Custom CRM) documentation guide](https://auto-respond.com/assets/docs/integrations-rest-webhook.svg "REST Webhook (Custom CRM) Documentation")

A visual guide to the REST Webhook (Custom CRM) documentation, covering the setup, configuration, and workflow details explained on this page. Documentation illustration for REST Webhook (Custom CRM).

# REST Webhook (Custom CRM)

The **REST Webhook (Custom CRM Integration)** is how you connect Auto-Respond to a CRM or internal system that isn’t one of the [directly-supported CRMs](https://auto-respond.com/docs/integrations/crm-systems/). Auto-Respond sends an HTTP POST request to an endpoint you control every time a lead event happens on this source - a new lead, new contact info, a new message. The payload is a JSON document containing the lead’s details, and every request carries a secret header so your endpoint can verify the request really came from Auto-Respond.

ℹ️

This integration requires a developer or someone who can host an endpoint that receives JSON. If you need a no-code route to a custom tool, use [Zapier](https://auto-respond.com/docs/integrations/zapier/) instead. If you just want a team alert, use [Slack](https://auto-respond.com/docs/integrations/slack/), [SMS](https://auto-respond.com/docs/integrations/sms/), or [Telegram](https://auto-respond.com/docs/integrations/telegram/).

## What you’ll get

- An HTTP POST to your endpoint for every lead event on this source.
- A JSON body with the lead’s identity, contact info, tags, and the conversation history so far.
- An `X-Secret-Key` header on every request so you can verify the sender.
- Optional handoff mode: Auto-Respond can stop sending its own welcome message and follow-ups and let your receiver drive the conversation.

## Connecting the Webhook

### Open the integration

In Auto-Respond, open the source → **Messaging Settings** → **Integrations** tab → **REST Webhook** card.

### Paste your Webhook URL

Enter the public HTTPS URL of the endpoint you want Auto-Respond to POST to. Your endpoint should accept JSON, respond with a `2xx` status on success, and be reachable from the public internet.

### Copy the Secret key

Auto-Respond generates a **Secret key** for you when the card is set up. This key is sent on every request in the `X-Secret-Key` HTTP header. Copy it into your receiver code and compare it against the incoming header on every request - reject any request where it doesn’t match.

You can **Regenerate** the secret key at any time. Regenerating invalidates the old key immediately - update your receiver before regenerating in production.

### Test webhook

Click **Test webhook** to send a sample POST to your URL right now. Check your endpoint’s logs to confirm it arrived, and confirm your signature check passes on the test request.

### Turn on the Enable toggle

The integration doesn’t POST anything until **Enable** is on.

## Options

### Enable

Turns the integration on or off for this source. Default: **off**.

### Inherit from parent

Only shown on a location with a parent business. When **on**, the location uses the parent’s webhook URL and secret. When **off**, it has its own.

### Webhook URL

The HTTPS endpoint that receives the POST. Required.

### Secret key

Auto-generated by Auto-Respond. Sent on every request as the `X-Secret-Key` HTTP header. Your receiver should reject any request whose header doesn’t match the key you configured. Click **Regenerate** to issue a new one - the old key stops working immediately.

### Skip welcome and follow-ups

Label: **Skip welcome and follow-ups**. Default: off.

- **When on** - Auto-Respond will **not** send its usual welcome message or follow-up sequence for leads on this source. The webhook receiver is expected to handle the conversation.
- **When off** - Auto-Respond sends its normal welcome and follow-ups in addition to firing the webhook.

Use this when your own system is taking over the conversation flow and you don’t want Auto-Respond’s automated messages to interfere.

### Create lead in CRM only when contact info is received

Label: **Create lead in CRM only when contact info is received**. Default: off.

- **When on** - your endpoint gets the lead only once the lead has shared a phone number or email, and only if **CRMs** is checked under **Trigger integrations:** in the source’s [Contact Info](https://auto-respond.com/docs/messaging-settings/contact-info/) tab for that kind of contact info.
- **When off** - your endpoint gets the lead as soon as the lead first reaches out, even before you have their contact info.

### Create only new leads

Label: **Create only new leads**. Default: off.

- **When on** - If your business had already messaged the lead before Auto-Respond first received the conversation, the lead’s contact info is not sent to your endpoint. New messages in a conversation don’t send the lead again either.
- **When off** - Those leads and messages are sent too.

This option looks at the conversation, not at your endpoint: it doesn’t search your endpoint for an existing record.

### Notify this integration only after the AI determines the lead is interested

Label: **Notify this integration only after the AI determines the lead is interested**. Default: off.

- Needs **AI Assistant** with **Short** or **Long** conversation in Conversation Setup.
- Can’t be turned on together with **Create lead in CRM only when contact info is received** or **Create only new leads**.

### Validate Connection / Test webhook

Fires a sample POST to the URL right now so you can confirm your endpoint receives it and your signature check works.

### Payload preview

The card has an expandable sample JSON block showing the shape of data Auto-Respond will POST to your endpoint.

### Disconnect

Clears the webhook URL and secret and turns the integration off. Confirmation required.

## Sample payload

The request is an HTTP POST with a JSON body. The `X-Secret-Key` header is set to your secret key. The body looks like:

```
{
  "message": "New lead created",
  "data": {
    "lead_id": "lead_01HX7Q5W9J2E8K1M3YPABCDEFG",
    "email": "alex@example.com",
    "phone": "+15551234567",
    "firstName": "Alex",
    "lastName": "Rivera",
    "postalCode": "90210",
    "tags": ["Yelp - Downtown"],
    "messages": [],
    "integrations": {}
  }
}
```

Fields:

- `message` - what happened, for example `New lead created`, `Lead interest confirmed`, or `Contact info is found in message:` followed by the message text.
- `data.lead_id` - identifier for the lead.
- `data.email`, `data.phone`, `data.postalCode` - present when collected.
- `data.firstName`, `data.lastName` - the customer’s name split into first and last.
- `data.tags` - holds the source’s name.
- `data.messages` - the conversation messages stored on the lead.
- `data.integrations` - what Auto-Respond has recorded for this lead in other integrations.

## What your endpoint should do

- Accept `POST` at the configured URL.
- Read the `X-Secret-Key` header and compare it to the secret you copied out of the card. Reject any request where it doesn’t match.
- Return a `2xx` status code on success. Any other status is treated as a delivery failure.
- Be idempotent - the same `lead_id` may arrive more than once as a lead updates.

## Disconnecting

Open the REST Webhook card → click **Disconnect** → confirm. The webhook URL and secret are cleared. Regenerating or disconnecting invalidates the old secret immediately.

## Troubleshooting

- **“Validation failed” / test webhook fails** - The endpoint didn’t return a `2xx` response in time. Check the URL, that the endpoint is publicly reachable over HTTPS, and that it responds quickly.
- **Signature check failing on my side** - Make sure you’re comparing against the **current** secret on the card. If you regenerated the secret, the old one stops working immediately.
- **Not receiving anything** - Confirm **Enable** is on. If **Create lead in CRM only when contact info is received** is on, the lead hasn’t shared phone or email yet, or **CRMs** isn’t checked in the Contact Info tab. If **Create only new leads** is on, your business may have messaged the lead before Auto-Respond received the conversation.
- **Auto-Respond is still sending welcome messages after my webhook fires** - Turn on **Skip welcome and follow-ups** if you want to fully hand the conversation over to your receiver.
- **I want duplicate protection** - Use the `lead_id` field in the payload as an idempotency key.

***

Questions about the REST Webhook integration? Email <support@auto-respond.com>.

Last updated: July 3, 2026