Developers

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

  1. Add a webhook in the CRM under API & Webhooks → Webhooks (organisation owner or admin): your HTTPS address and the events you want.
  2. Copy the signing secret (whsec_…). It is shown once — keep it on your server.
  3. Grocito sends a POST with a JSON body for each event, signed with that secret. Answer with any 2xx within 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.

Webhook events
EventWhenIn data
lead.createdLead createdobject = the lead
lead.updatedLead updatedobject = the lead; previous = the changed fields before the change
lead.status_changedLead status changedobject = the lead; previous.status
lead.assignedLead assignedobject = the lead; previous.assigned_to
lead.archivedLead archivedobject = the lead
lead.unarchivedLead restored from archiveobject = the lead
note.addedNote addedobject = the lead; note = the new note
deal.createdDeal createdobject = the lead; deal = the new deal
deal.stage_changedDeal stage changedobject = the lead; deal; previous.stage
deal.wonDeal wonobject = the lead; deal; previous.stage
reminder.createdReminder createdobject = the reminder
reminder.completedReminder completedobject = the reminder
call.loggedCall loggedobject = the call log
order.createdStore order placedneeds E-commerce (online store) pluginobject = 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.

Webhook body (JSON)
{
  "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

Webhook request headers
HeaderValue
webhook-idThe event id — the same as id in the body.
webhook-timestampWhen it was sent, in Unix seconds.
webhook-signaturev1,<base64 signature> — two of them, separated by a space, for 24 hours after you rotate the secret.
Content-Typeapplication/json
User-AgentGrocito-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:

  1. Take the secret without its whsec_ prefix and base64-decode it — that is the key.
  2. Build the text webhook-id + "." + webhook-timestamp + "." + raw body. Use the body exactly as received, before any JSON parsing.
  3. Compute HMAC-SHA256 of that text with the key and base64-encode it.
  4. Accept the delivery if it equals any v1, signature in webhook-signature (compare in constant time), and if webhook-timestamp is 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);

Replace YOUR_WEBHOOK_SECRET with your secret — better, read it from an environment variable.

Responses and retries

How Grocito treats your answer
Your server answersWhat Grocito does
2xxDelivered.
429, 5xx, a timeout (10 s) or no connectionRetries up to 7 more times over about an hour — after 30 seconds, then 1, 2, 4, 8, 16 and 32 minutes.
410 GoneSwitches 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 event id) 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 ping event (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.
A ping event (JSON)
{
  "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.

Back to the API reference