---
title: "Webhooks overview"
description: "OnePageCRM POSTs to your URL when CRM data changes. What webhooks are, how to activate them, and the five-key payload."
canonical_url: https://developer.onepagecrm.com/webhooks/overview/
source: Markdown mirror of https://developer.onepagecrm.com/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/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](/api/reference/) |
| Ask questions about current state ("won deals this quarter") | **[OQL](/oql/overview/)** via the [MCP server](/mcp/overview/) |

These aren't exclusive. Webhook delivery is
[at-most-once](/webhooks/delivery/) — 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](/webhooks/manage/).

Use an HTTPS URL, and set a secret key — it's how your endpoint
verifies a request really came from OnePageCRM. See
[Security](/webhooks/security/).

## The payload at a glance

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

```json
{
  "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](/webhooks/payloads/) page.

## Common questions

**Do webhooks retry failed deliveries?**
No. Delivery is [at-most-once](/webhooks/delivery/) — 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](/webhooks/security/), 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](/webhooks/events/).

## What's in this section

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

New here? Start with the
[webhooks tutorial](/tutorials/webhooks/) — activate the app, catch
your first event, and build a verified receiver.