Inbound webhooks

An inbound webhook is a URL that belongs to one Couplr company. Another system sends data to it with an HTTP POST. Couplr stores what arrived, then uses a field mapping you set up to create or update a customer, or to create a job.

Use one when the other system can send data to a URL but cannot call an API, for example a website form, an ad lead form routed through Zapier, or a scheduling tool.

Set up an endpoint#

A company admin does this on the Integrations page (https://couplrfsm.com/dashboard/integrations), in the "Receive data" section.

1. Choose New webhook and give it a name, such as "Website contact form".
2. Leave Require a signature (advanced) off unless the sending app can sign its requests. See Sender authentication.
3. Copy the webhook URL. It looks like https://couplrfsm.com/hooks/YOUR_WEBHOOK_TOKEN. If you turned signatures on, also copy the signing secret. It is shown once.
4. Get a sample: have the sending app send one real submission to the URL, or paste an example payload.
5. Review the field mapping Couplr proposes, adjust it and save. See Field mapping.
6. Turn the webhook on. Its status changes from "Waiting for a sample" to "Active".

The URL contains a long random token that identifies the endpoint and the company. Treat the whole URL as a secret. The company is always taken from the endpoint. A company or tenant id inside the payload has no effect.

Send data#

Send a POST to the webhook URL with one of:

• A JSON object: Content-Type: application/json.
• A JSON array of objects. Each element is treated as a separate event. At most 25 per request.
• A form post: application/x-www-form-urlencoded, including nested keys such as contact[email], or multipart/form-data fields. Uploaded files are ignored. A signed webhook (hmac or standard_webhooks) can't verify multipart/form-data and answers 415; send JSON or a urlencoded form instead.

curl -X POST "https://couplrfsm.com/hooks/YOUR_WEBHOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Event-Id: lead-8841" \
  -d '{"name": "Dana Whitfield", "email": "dana@example.com", "phone": "555-201-8890"}'

Optional headers:

Limits:

Couplr never fetches URLs, downloads attachments or runs anything found in a payload. Links and file references arrive as plain text.

Sender authentication#

An endpoint works in one of two ways, chosen when it is created.

Secret URL (default). The URL is the only credential. Anyone who has the URL can send data to it. This is the only choice for senders that cannot add headers, and it is what most form tools and automation steps use. It proves the sender knows the URL. It does not prove who sent the request or that the body was not changed in transit by something that also knows the URL. If the URL may have leaked, delete the webhook and create a new one.

Signature required. With "Require a signature" on, every request must carry an X-Hvacpro-Signature header holding the hex HMAC-SHA256 of the request, computed with the signing secret. A request with a missing or wrong signature gets 401 and is not stored or processed. There is no fallback to the secret URL.

Sign one of two ways:

1. Recommended. Also send X-Hvacpro-Timestamp with the current Unix time in seconds, and sign the string TIMESTAMP.BODY, where BODY is the exact bytes you send. The timestamp must be within 5 minutes of the current time, so a captured request cannot be replayed later.
2. Without the timestamp header, sign the exact body bytes alone.

BODY='{"name":"Dana Whitfield","email":"dana@example.com"}'
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "YOUR_SIGNING_SECRET" -hex | sed 's/^.* //')
curl -X POST "https://couplrfsm.com/hooks/YOUR_WEBHOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Hvacpro-Timestamp: $TS" \
  -H "X-Hvacpro-Signature: $SIG" \
  -d "$BODY"

The signature may be prefixed with sha256=. Sign the bytes you actually send: re-serializing the JSON after signing changes the bytes and the signature will not match.

Test events#

• While a webhook is "Waiting for a sample", the first request it receives is saved as the sample used to build the mapping. Nothing is created in Couplr.
• You can paste an example payload instead of sending one.
• Requests received before the webhook is turned on are stored with status "Skipped" and create nothing. After you turn the webhook on you can replay a skipped event from its activity list.

There is no separate test mode in the Integrations screens yet that previews what a live event would create. To try a mapping safely, send a test submission with a contact you recognize, check the result in the activity list, then delete the test customer.

Field mapping#

A mapping says which record to create and where each of its fields comes from. Couplr proposes one from your sample. You can edit every row.

Records:

Customer fields: name, email, phone, address, city, state, zip_code. Job fields: scheduled_date, notes.

Each field takes its value one of three ways:

Matching an existing customer: Couplr looks for a customer in your company with the same email, then the same phone number. A phone number only matches when it is a full 10-digit number, with or without a leading 1; shorter values never match. When one is found, the mapping's "When a matching customer already exists" setting decides whether to update their details or skip the event.

Other options:

• Start a Speed to Lead text conversation with new leads. Texts the homeowner as soon as a new customer is created. It is off unless you turn it on, and it never runs for a customer who already existed.
• Mapped values go through the same validation as the Couplr apps. An event whose values are invalid, such as a malformed email, fails with the reason shown. See Processing status.

Acknowledgments#

Couplr answers as soon as the event is safely stored. The answer means "received", not "processed": the customer or job is created a moment later in the background.

Treat any 2xx as success. On 429 and 5xx, send the same request again later. Do not retry other 4xx responses without changing the request.

Processing status#

Each event appears in the webhook's "Recent activity" list on the Integrations page with one of these statuses:

A failed or skipped event can be replayed from the list once the webhook is active. A replay runs the event again with the current mapping, so the usual fix for a failed event is: correct the mapping, save, replay.

Stored events are kept for 90 days, then deleted. Deleting a webhook deletes its stored events.

Duplicates#

Senders retry, so the same event can arrive more than once. Couplr recognizes a repeat in two ways:

• By event id. When you send X-Event-Id, a second request with the same id to the same endpoint is a duplicate, whatever its body. Ids are case-sensitive and belong to one endpoint. This is the reliable method. Use it when you can.
• By body. Without an event id, a request whose body is byte-for-byte identical to one received on the same endpoint in the last 24 hours is a duplicate. Two different people submitting identical data would also match, and a retry that re-serializes its JSON differently would not.

On a webhook that requires a signature, both checks apply.

Processing is safe to repeat: a customer is matched and updated instead of created twice, and a job is tied to the event that created it, so replaying that event does not book a second job.

Retries#

• Sending. If you get no response, a 429 or a 5xx, send the request again. Use the same X-Event-Id so a request that did arrive is not processed twice.
• Processing. If processing fails for a temporary reason, Couplr tries again, up to 3 attempts in total, then marks the event "Failed". Invalid data fails at once without further attempts.
• Order. Events may be processed in a different order from the order they were sent. Do not rely on order.

Troubleshooting#

Not available yet#

These are built into the service but cannot be set from the Integrations screens today, so do not plan on them:

• Bearer-token authentication for senders, and verification of Standard Webhooks signatures.
• Replacing a signing secret or a webhook URL in place. Delete the webhook and create a new one instead.
• A preview mode that shows what an event would create without creating it.
• Default values, required fields and type conversion in mappings, and matching customers by the sender's own id.