Platform
PreviewWebhooks
Place tells your system when a lead changes. Each change is a signed event sent to an HTTPS endpoint you register.
Preview: events recorded, use Send test in the Console
webhook.test event.Event types
There is one event per public lead status. Events are recorded per project and environment.
| Event | Sent when the lead becomes |
|---|---|
lead.received | received |
lead.validated | validated |
lead.assigned | assigned |
lead.contacted | contacted |
lead.appointment_created | appointment |
lead.won | won |
lead.lost | lost |
webhook.test | Never. Sent only when you press Send test in the Console. |
Request and payload
Each event is a POST with a JSON body. The data object is the lead exactly as the Lead API returns it, so one parser handles both.
POST /your/webhook/endpoint
Content-Type: application/json
Place-Event-Id: evt_7Hc2…
Place-Timestamp: 1789116060
Place-Signature: t=1789116060,v1=5f0c1e…{
"id": "evt_7Hc2…",
"object": "event",
"type": "lead.assigned",
"environment": "production",
"created_at": "2026-09-11T09:52:13.000Z",
"data": {
"id": "pl_lead_8a1f3c",
"object": "lead",
"external_id": "lead_82716",
"status": "assigned",
"environment": "production",
"created_at": "2026-09-11T09:41:00.000Z"
}
}data may still gain fields before delivery goes live. Ignore fields you do not know.Registering an endpoint
- Add the endpoint in the Console under Webhooks, per project and environment.
- The URL must use
https. Events contain lead data. - Credentials in the URL, localhost, private network addresses and IPv6 literals are rejected.
- You get a signing secret starting with
whsec_. The Console shows it once. Store it next to your API key.
Testing your endpoint
Send test delivers one signed webhook.test event with the same headers as a lead event. Its data holds only a short message. Place waits up to five seconds, does not follow redirects and records the attempt with its response code under Deliveries. Your response body is never stored or shown.
Verifying signatures
Every request is signed with your endpoint's secret. The Place-Signature header holds a Unix timestamp t and an HMAC-SHA256 v1 of the string <t>.<raw body>, in hex.
- Split the header at commas and read
tandv1. - Reject the event if t is more than five minutes away from your clock.
- Compute the HMAC of
t + "." + rawBodywith your secret. - Compare it with v1 in constant time.
import crypto from "node:crypto";
// rawBody: the request body exactly as received, before JSON.parse.
export function verifyPlaceSignature(secret, header, rawBody, toleranceSec = 300) {
const parts = Object.fromEntries(
header.split(",").map((p) => p.trim().split("=", 2)),
);
const t = Number(parts.t);
if (!Number.isFinite(t) || !parts.v1) return false;
// Older than five minutes: replayed or intercepted.
if (Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
const expected = crypto
.createHmac("sha256", secret)
.update(`${t}.${rawBody}`)
.digest("hex");
const a = Buffer.from(expected);
const b = Buffer.from(parts.v1);
return a.length === b.length && crypto.timingSafeEqual(a, b);
}Use the raw body
Receiving events
- Answer with any
2xxquickly. Do the actual work after responding, for example in a queue. - De-duplicate by
Place-Event-Id. The same event can arrive more than once. - Do not rely on order. Use the lead's
statusindata, or read the lead withGET /v1/leads/{id}when in doubt. - Anything other than
2xx, or no answer, counts as a failed delivery.
app.post("/webhooks/place", express.raw({ type: "application/json" }), async (req, res) => {
const raw = req.body.toString("utf8");
if (!verifyPlaceSignature(process.env.PLACE_WEBHOOK_SECRET, req.get("Place-Signature") ?? "", raw)) {
return res.sendStatus(400);
}
const event = JSON.parse(raw);
if (await alreadyProcessed(event.id)) return res.sendStatus(200);
res.sendStatus(200); // answer first …
await queue.push(event); // … then do the work
});Retries
Place records every delivery attempt with its response code and duration. Test events are sent once and not retried. A retry schedule for lead events will be published here before their delivery goes live. Until then, design your receiver to be idempotent. That covers any schedule.