Webhooks overview

Webhooks push CRM changes to you. Instead of polling the API to ask “did anything change?”, you register a URL and OnePageCRM sends a POST to it shortly after a contact, deal, action, note, call, meeting, or company changes.

That means less traffic on both sides, and your integration reacts when the change happens — not when your next poll runs.

No retries. Delivery is at-most-once — a failed delivery is not re-sent. Pair webhooks with a reconciliation poll. See Delivery.

Webhooks, polling, or OQL?

You want to	Use
React to changes as they happen	Webhooks
Guarantee you have every record, even if a delivery was missed	Polling the REST API
Ask questions about current state (“won deals this quarter”)	OQL via the MCP server

These aren’t exclusive. Webhook delivery is at-most-once — a failed delivery is not retried — so the reliable pattern is webhooks for freshness plus a periodic reconciliation poll for completeness.

Activate webhooks

An account administrator opens Apps in OnePageCRM and activates the Webhooks app, then configures a name, a target URL, a format (json), and a secret key. See Manage webhooks.

Use an HTTPS URL, and set a secret key — it’s how your endpoint verifies a request really came from OnePageCRM. See Security.

The payload at a glance

Every webhook is a POST with exactly five top-level keys:

{
  "type": "contact",
  "reason": "updated",
  "timestamp": 1781426730,
  "secretkey": "your-configured-secret",
  "data": {
    "contact": { "id": "5aba31ea9007ba0f570c92d4", "first_name": "Jane", "...": "..." },
    "next_actions": ["..."],
    "...": "..."
  }
}

Key	What it is
type	The entity that changed: contact, company, deal, action, note, call, meeting
reason	What happened: created, updated, deleted, changed_to_won, …
timestamp	Unix time in seconds (integer)
secretkey	Your configured secret
data	The changed resource, nested under its entity key (data.contact, data.deal, …) — same shape as the API v3 response. Deleted events are the exception: data is just { "id": "..." }

Full details, encodings, and realistic samples are on the Payloads page.

Common questions

Do webhooks retry failed deliveries? No. Delivery is at-most-once — a failed delivery is not re-sent. Treat webhooks as a freshness signal and pair them with a periodic reconciliation poll against the REST API.

How do I verify a webhook came from OnePageCRM? Every delivery carries your configured secret in the secretkey body field. Compare it against your stored secret with a constant-time comparison, reject requests that don’t match, and always use an HTTPS endpoint.

Which events are covered? Created, updated, and deleted events for all seven core entities, plus action completions and deal status changes to pending, won, or lost. The full matrix is on Events.

What’s in this section

• Events. The full entity × reason matrix, dynamic deal status events, what triggers webhooks and what doesn’t, and privacy exclusions.
• Payloads. The envelope, sample payloads, and the deleted-event rule.
• Delivery. Dispatch timing, how fast to respond, at-most-once semantics, and how to build around them.
• Security. Verifying the secret key with a constant-time compare, and an honest look at the threat model.
• Manage webhooks. Setting up webhook configs in the Apps page, and the fields each one takes.

New here? Start with the webhooks tutorial — activate the app, catch your first event, and build a verified receiver.