Developers

Webhooks

Get a signed HTTPS POST the moment a review arrives, is answered or changes, when Grades.com AI needs an approval, and when a customer acts on a review request.

Register an endpoint

POST /v1/webhooks with the HTTPS url, the events you want (all of them if you leave it out) and the company uuid. It needs the scope reviews:write and a plan with webhooks (Pro or Premium; otherwise 402). The answer (201) carries the signing secret whsec_..., shown only this once.

Register a webhook endpoint
curl https://app.grades.com/api/v1/webhooks \
  -H "Authorization: Bearer $GRADES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/grades/webhook",
    "events": ["review.created", "review.replied"],
    "company": "COMPANY_UUID"
  }'
OperationWhat it does
POST /v1/webhooksRegisters an endpoint. Registering the same URL for the same business again answers 200 with the existing endpoint (meta.existing: true, no secret) when the events match, or 409 endpoint_exists when they differ
GET /v1/webhooksYour endpoints
DELETE /v1/webhooks/{id}Removes an endpoint (204); the Location header of the create answer is its address
GET /v1/webhooks/eventsEvery event with a description and an example
GET /v1/webhooks/samples?event=&company=Sample bodies in the exact delivery shape, built from your business's data, to test your receiver without waiting for a real event
  • Up to 25 active endpoints per location, and 200 per user across businesses.
  • The URL must be HTTPS and carry no user name or password. Deliveries do not follow redirects.
  • A key or connection limited to some businesses must name one of them in company.

Events

EventSent when
review.createdA new review was found on a review site or left on Grades.com
review.updatedA review's text, rating or reply changed, or it was removed or restored (data.changes lists what)
review.removedA review was removed from its site; it stays in your archive (data.removal_reason)
review.repliedA review got a reply, or its reply changed (data.response)
review.taggedA review got or lost a tag, or its sentiment changed (by a person, or by Grades.com on a new review)
agent.action.pendingGrades.com AI queued reply drafts or reports that wait for approval
agent.action.postedAn agent action was carried out: a reply posted or a report filed
source.reconnect_requiredA connected review site lost its authorization and must be reconnected
radar.mention.foundReview Monitoring found new pages that mention the business
radar.ai_perception.changedAn AI assistant's view of the business changed, or it states a new complaint
review_request.clickedA customer clicked the link in a review request
review_request.visitedA customer opened the review page from a review request
review_request.reviewedA customer left a review after a review request
review_request.unsubscribedA customer opted out of review requests
recovery.case.openedA Review Disputes case opened for an unhappy customer (a 1 or 2 star review, private feedback or an escalation)

The review request events cover requests sent by email; text-message review requests are Coming soon

Payload

Every delivery has the same envelope: the event id, its type, when it happened, the business and the event's data. Review events carry the review in the same shape as GET /v1/companies/{company}/reviews/{review}.

review.created (review trimmed)
POST /grades/webhook HTTP/1.1
Content-Type: application/json
User-Agent: Grades-Webhooks/1
X-Grades-Event: review.created
X-Grades-Delivery: 0f9a3c52-6d1e-4b8e-9a51-2f7c1d3e8b40
X-Grades-Signature: t=1795075200,v1=5f2b6c1e…

{
  "id": "0f9a3c52-6d1e-4b8e-9a51-2f7c1d3e8b40",
  "type": "review.created",
  "created_at": "2026-11-19T14:00:00Z",
  "company": {
    "uuid": "8c1d…",
    "name": "Wrenfield Dental Studio",
    "hub_client_id": null,
    "hub_location_key": null
  },
  "data": {
    "review": {
      "uuid": "b71e…",
      "site": "google",
      "rating": 5,
      "text": "Gentle cleaning and they explained everything.",
      "author": "Jane D.",
      "published_at": "2026-11-19T13:52:10Z",
      "external_url": "https://…",
      "response_text": null,
      "text_policy": null,
      "…": "…"
    }
  }
}

Webhooks never carry Yelp review text: a Yelp review arrives with its rating, date, site and link, and text, author, avatar and response_text set to null (fetch it through the API with recorded consent if you need it). Use GET /v1/webhooks/samples for the exact shape of every other event.

Headers

HeaderValue
X-Grades-EventThe event type, for example review.created
X-Grades-DeliveryThe event id (the body's id). The same on every retry of that event: use it to drop duplicates
X-Grades-Signaturet=<unix seconds>,v1=<hex>: the HMAC-SHA256 of <t>.<raw body> keyed with your endpoint secret
User-AgentGrades-Webhooks/1

Check the signature

Compute the HMAC over the raw body exactly as received (before any JSON parsing), compare it in constant time, and reject a timestamp more than 5 minutes away from your clock. Each attempt is signed with a fresh timestamp.

Check the signature of a delivery
import crypto from 'node:crypto';

// rawBody: the request body exactly as received (a string, before JSON.parse)
// header:  the X-Grades-Signature header, "t=<unix seconds>,v1=<hex>"
export function isFromGrades(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(String(header).split(',').map((pair) => pair.split('=', 2)));
  if (!parts.t || !parts.v1) return false;
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > toleranceSeconds) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex');
  return expected.length === parts.v1.length
    && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

Answering, retries and duplicates

  • Answer with any 2xx within 5 seconds (2 seconds to connect). Do the work after you answer, in a queue.
  • Any other answer, a timeout or a redirect counts as a failure. The delivery is tried again after 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours, then given up (the last try is about 15 hours after the first).
  • After 20 failed deliveries in a row the endpoint is switched off. Fix the receiver, then register the URL again.
  • An event can arrive more than once and out of order: dedupe with X-Grades-Delivery and use the review's own dates to decide what is newest.
  • A review you add with POST /v1/companies/{company}/reviews does not come back as review.created to the endpoints registered by the same key or app connection, so an integration that writes reviews does not hear its own writes.