Webhooks
Grocito CRM tells your server the moment a lead, deal, note, reminder, call or store order changes — a signed JSON POST to your HTTPS address, retried if your server is down.
On this page
How it works
- Add a webhook in the CRM under API & Webhooks → Webhooks (organisation owner or admin): your HTTPS address and the events you want.
- Copy the signing secret (
whsec_…). It is shown once — keep it on your server. - Grocito sends a POST with a JSON body for each event, signed with that secret. Answer with any
2xxwithin 10 seconds.
Webhooks per organisation, by plan: Starter 1, Growth 5, Pro / Business 10. Trials have no webhooks. Webhooks need the API & Webhooks plugin on your plan — see the API overview.
Events
Choose any of these 14 events for each webhook.
| Event | When | In data |
|---|---|---|
lead.created | Lead created | object = the lead |
lead.updated | Lead updated | object = the lead; previous = the changed fields before the change |
lead.status_changed | Lead status changed | object = the lead; previous.status |
lead.assigned | Lead assigned | object = the lead; previous.assigned_to |
lead.archived | Lead archived | object = the lead |
lead.unarchived | Lead restored from archive | object = the lead |
note.added | Note added | object = the lead; note = the new note |
deal.created | Deal created | object = the lead; deal = the new deal |
deal.stage_changed | Deal stage changed | object = the lead; deal; previous.stage |
deal.won | Deal won | object = the lead; deal; previous.stage |
reminder.created | Reminder created | object = the reminder |
reminder.completed | Reminder completed | object = the reminder |
call.logged | Call logged | object = the call log |
order.created | Store order placedneeds E-commerce (online store) plugin | object = the store order |
Objects are exactly what the API returns: Lead, Note, Deal, Reminder, Call, Order.
Payload
Every delivery has the same envelope:
idstring- Event id = the webhook-id header. Deliveries can repeat: skip ids you already handled.
typestring- One of:
lead.created,lead.updated,lead.status_changed,lead.assigned,lead.archived,lead.unarchived,note.added,deal.created,deal.stage_changed,deal.won,reminder.created,reminder.completed,call.logged,order.created api_versionstring- One of:
v1 created_atstring (date-time)can be null- —
organization_idstring- —
dataobject- —
data.objectobject- The lead / reminder / call / order, exactly as the API returns it.
data.previousobject- Changed fields before the change (lead.updated / status_changed / assigned / deal.stage_changed).
data.dealDeal- —
data.noteNote- —
metaobject- —
meta.caused_byobject- —
meta.caused_by.typestring- api = made through the public API (api_key_id says which key); crm = any other change (a CRM user, an automation or an integration). Decided only from server-set data. One of:
api,crm meta.caused_by.api_key_idstring- —
meta.truncatedboolean- —
meta.caused_by says where the change came from: { "type": "api", "api_key_id": "…" } for a change made through the API (with the key that made it), and { "type": "crm" } for every other change — a person in the CRM, an automation or an integration. Only data our servers set decides it, so it cannot be faked by what a record contains. If a payload would be larger than 256 KB, bulky fields are left out and meta.truncated is true — read the record with the API.
Example: lead.status_changed
Made-up data.
{
"id": "evt_3f9a1c7e5b2d4a6c8e0f1a2b",
"type": "lead.status_changed",
"api_version": "v1",
"created_at": "2026-11-02T06:45:12.000Z",
"organization_id": "k7Qm2xR9tLw4Np8sVb3Z",
"data": {
"object": {
"id": "Hc4Tn8wQ2zLp6Rv1Ks9J",
"object": "lead",
"name": "Asha Verma",
"mobile": "9876543210",
"phone": "9876543210",
"email": "asha@example.com",
"status": "Interested",
"source": "Website",
"priority": "Medium",
"assigned_to": "u9WbX2mK5qTz8Lr3Nd6F",
"remark": "Asked for a demo",
"company": "Verma Handicrafts",
"archived": false,
"archived_at": null,
"archived_reason": null,
"decline_reason": null,
"custom_fields": {
"city": "Jaipur"
},
"deal_value": 45000,
"primary_deal_id": "Dl5Gh7Jk9Mn2Pq4Rs6Tu",
"deals_count": 1,
"received_at": "2026-11-02T04:30:00.000Z",
"created_at": "2026-11-02T04:30:05.000Z",
"updated_at": "2026-11-02T06:45:11.000Z",
"created_by": "u9WbX2mK5qTz8Lr3Nd6F",
"updated_by": "u9WbX2mK5qTz8Lr3Nd6F"
},
"previous": {
"status": "New"
}
},
"meta": {
"caused_by": {
"type": "crm"
}
}
}Headers
| Header | Value |
|---|---|
webhook-id | The event id — the same as id in the body. |
webhook-timestamp | When it was sent, in Unix seconds. |
webhook-signature | v1,<base64 signature> — two of them, separated by a space, for 24 hours after you rotate the secret. |
Content-Type | application/json |
User-Agent | Grocito-Webhooks/1.0 |
Verify signatures
Grocito signs every delivery the Standard Webhooks way, so many webhook libraries can check it for you. To check it yourself:
- Take the secret without its
whsec_prefix and base64-decode it — that is the key. - Build the text
webhook-id + "." + webhook-timestamp + "." + raw body. Use the body exactly as received, before any JSON parsing. - Compute HMAC-SHA256 of that text with the key and base64-encode it.
- Accept the delivery if it equals any
v1,signature inwebhook-signature(compare in constant time), and ifwebhook-timestampis within 5 minutes of your clock.
// Express: verify a Grocito CRM webhook (Standard Webhooks). Use the RAW body, not parsed JSON.
const crypto = require('crypto');
const express = require('express');
const SECRET = 'YOUR_WEBHOOK_SECRET'; // whsec_...
function verify(rawBody, headers) {
const id = headers['webhook-id'];
const ts = headers['webhook-timestamp'];
const sigHeader = headers['webhook-signature'] || '';
if (!id || !ts || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false; // 5-minute window
const key = Buffer.from(SECRET.replace(/^whsec_/, ''), 'base64');
const expected = crypto.createHmac('sha256', key).update(`${id}.${ts}.${rawBody}`).digest('base64');
return sigHeader.split(' ').some((part) => {
const [version, sig] = part.split(',');
return version === 'v1' && sig && sig.length === expected.length
&& crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
});
}
const app = express();
app.post('/grocito-webhook', express.raw({ type: 'application/json' }), (req, res) => {
if (!verify(req.body.toString('utf8'), req.headers)) return res.status(401).end();
const event = JSON.parse(req.body.toString('utf8'));
// Deliveries can repeat: skip an event id you have already handled.
console.log(event.type, event.data.object.id);
res.status(200).end();
});
app.listen(3000);<?php
// Verify a Grocito CRM webhook (Standard Webhooks).
$secret = 'YOUR_WEBHOOK_SECRET'; // whsec_...
$raw = file_get_contents('php://input');
$id = $_SERVER['HTTP_WEBHOOK_ID'] ?? '';
$ts = $_SERVER['HTTP_WEBHOOK_TIMESTAMP'] ?? '';
$sigHeader = $_SERVER['HTTP_WEBHOOK_SIGNATURE'] ?? '';
if ($id === '' || $ts === '' || abs(time() - (int) $ts) > 300) { http_response_code(401); exit; }
$key = base64_decode(preg_replace('/^whsec_/', '', $secret));
$expected = base64_encode(hash_hmac('sha256', $id . '.' . $ts . '.' . $raw, $key, true));
$ok = false;
foreach (explode(' ', $sigHeader) as $part) {
$p = explode(',', $part, 2);
if (count($p) === 2 && $p[0] === 'v1' && hash_equals($expected, $p[1])) { $ok = true; }
}
if (!$ok) { http_response_code(401); exit; }
$event = json_decode($raw, true);
// Deliveries can repeat: skip an event id you have already handled.
error_log($event['type']);
http_response_code(200);# Flask: verify a Grocito CRM webhook (Standard Webhooks).
import base64, hashlib, hmac, json, time
from flask import Flask, request, abort
SECRET = "YOUR_WEBHOOK_SECRET" # whsec_...
app = Flask(__name__)
def verify(raw: bytes, headers) -> bool:
msg_id = headers.get("webhook-id", "")
ts = headers.get("webhook-timestamp", "")
sig_header = headers.get("webhook-signature", "")
if not msg_id or not ts or abs(time.time() - int(ts)) > 300: # 5-minute window
return False
key = base64.b64decode(SECRET.removeprefix("whsec_"))
signed = f"{msg_id}.{ts}.".encode() + raw
expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()
for part in sig_header.split(" "):
version, _, sig = part.partition(",")
if version == "v1" and hmac.compare_digest(sig, expected):
return True
return False
@app.post("/grocito-webhook")
def grocito_webhook():
raw = request.get_data()
if not verify(raw, request.headers):
abort(401)
event = json.loads(raw)
# Deliveries can repeat: skip an event id you have already handled.
print(event["type"])
return "", 200Replace YOUR_WEBHOOK_SECRET with your secret — better, read it from an environment variable.
Responses and retries
| Your server answers | What Grocito does |
|---|---|
2xx | Delivered. |
429, 5xx, a timeout (10 s) or no connection | Retries up to 7 more times over about an hour — after 30 seconds, then 1, 2, 4, 8, 16 and 32 minutes. |
410 Gone | Switches the webhook off. Turn it on again in the CRM when you are ready. |
| Anything else (other 4xx, 3xx) | Marked failed, not retried. Redirects are not followed. |
If deliveries fail 20 times or more in a row over more than 24 hours, the webhook is switched off automatically and the organisation’s admins are notified. Fix the endpoint, then switch it back on.
- A webhook is paused when the admin who created it is no longer an active admin. A current admin can turn it on again (after a recent sign-in) and becomes its owner.
- The platform can lock an organisation’s API & Webhooks or switch its webhooks off. Those webhooks show Disabled by the platform and cannot be turned on until the platform unlocks them.
Answer quickly: store the event and reply 2xx, then do the slow work afterwards.
Handle repeats
A delivery can arrive more than once — after a timeout, a retry or a Resend — and a retried delivery can arrive after a newer one. So:
- Remember the
webhook-id(the eventid) of events you have handled and skip ones you have seen. - Use the record’s
updated_at, or read it fresh with the API, rather than assuming the order of arrival.
Security
- Addresses must be
https://on port 443 and reach a public internet address; private and internal addresses are refused. - Deliveries do not come from fixed IP addresses — check the signature instead of allow-listing IPs.
- Keep the secret on your server. If it leaks, rotate it in the CRM: for 24 hours both the old and the new secret sign each delivery, so you can switch without missing any.
- Reject deliveries with a missing or wrong signature, or a timestamp more than 5 minutes off.
Testing and the delivery log
- Send test on a webhook delivers one
pingevent (sent once, not retried) and shows you the answer. - The Deliveries tab lists the last 50 events sent to your webhooks with your server’s answers. Payloads are kept for 7 days (the log for 30). Resend sends one again.
{
"id": "evt_test_5c2e8a1f9b3d7e40",
"type": "ping",
"api_version": "v1",
"created_at": "2026-11-02T06:50:00.000Z",
"organization_id": "k7Qm2xR9tLw4Np8sVb3Z",
"data": {
"object": {
"object": "ping",
"message": "Test event from Grocito CRM — your endpoint is reachable."
}
},
"meta": {
"caused_by": {
"type": "crm"
}
}
}Avoid loops
If your system reacts to a webhook by updating the same lead through the API, that update fires a webhook too. To stop the echo, tick Ignore changes made by these keys on the webhook and pick the keys your system uses — changes made with them are not sent to that webhook. meta.caused_by also tells you which key made a change.