Platform

Preview

Webhooks

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

Place records every lead event for your project, and the Console lists them under Events. Automatic delivery of lead events to your endpoint is not switched on yet. To check your receiver today, press Send test on the endpoint. Place then sends a real, signed webhook.test event.

Event types

There is one event per public lead status. Events are recorded per project and environment.

EventSent when the lead becomes
lead.receivedreceived
lead.validatedvalidated
lead.assignedassigned
lead.contactedcontacted
lead.appointment_createdappointment
lead.wonwon
lead.lostlost
webhook.testNever. 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"
  }
}
The headers and the signature scheme are final. The envelope around 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.

  1. Split the header at commas and read t and v1.
  2. Reject the event if t is more than five minutes away from your clock.
  3. Compute the HMAC of t + "." + rawBody with your secret.
  4. 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

Verify the bytes you received. Parsing and re-serialising the JSON changes whitespace and key order, and the signature no longer matches.

Receiving events

  • Answer with any 2xx quickly. 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 status in data, or read the lead with GET /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.