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.
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"
}'const res = await fetch(`${API}/webhooks`, {
method: 'POST',
headers: { ...headers, 'Content-Type': 'application/json' },
body: JSON.stringify({
url: 'https://example.com/grades/webhook',
events: ['review.created', 'review.replied'],
company: 'COMPANY_UUID',
}),
});
const { data: endpoint } = await res.json();
// Store endpoint.secret now (whsec_...): it is shown only in this answer.
console.log(res.status, endpoint.secret);r = requests.post(f"{API}/webhooks", headers=headers, timeout=30, json={
"url": "https://example.com/grades/webhook",
"events": ["review.created", "review.replied"],
"company": "COMPANY_UUID",
})
r.raise_for_status()
endpoint = r.json()["data"]
# Store endpoint["secret"] now (whsec_...): it is shown only in this answer.
print(r.status_code, endpoint["secret"])$res = $grades->post('webhooks', ['json' => [
'url' => 'https://example.com/grades/webhook',
'events' => ['review.created', 'review.replied'],
'company' => 'COMPANY_UUID',
]]);
$endpoint = json_decode((string) $res->getBody(), true)['data'];
// Store $endpoint['secret'] now (whsec_...): it is shown only in this answer.
echo $res->getStatusCode(), ' ', $endpoint['secret'], PHP_EOL;| Operation | What it does |
|---|---|
POST /v1/webhooks | Registers 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/webhooks | Your endpoints |
DELETE /v1/webhooks/{id} | Removes an endpoint (204); the Location header of the create answer is its address |
GET /v1/webhooks/events | Every 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
| Event | Sent when |
|---|---|
review.created | A new review was found on a review site or left on Grades.com |
review.updated | A review's text, rating or reply changed, or it was removed or restored (data.changes lists what) |
review.removed | A review was removed from its site; it stays in your archive (data.removal_reason) |
review.replied | A review got a reply, or its reply changed (data.response) |
review.tagged | A review got or lost a tag, or its sentiment changed (by a person, or by Grades.com on a new review) |
agent.action.pending | Grades.com AI queued reply drafts or reports that wait for approval |
agent.action.posted | An agent action was carried out: a reply posted or a report filed |
source.reconnect_required | A connected review site lost its authorization and must be reconnected |
radar.mention.found | Review Monitoring found new pages that mention the business |
radar.ai_perception.changed | An AI assistant's view of the business changed, or it states a new complaint |
review_request.clicked | A customer clicked the link in a review request |
review_request.visited | A customer opened the review page from a review request |
review_request.reviewed | A customer left a review after a review request |
review_request.unsubscribed | A customer opted out of review requests |
recovery.case.opened | A 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}.
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
| Header | Value |
|---|---|
X-Grades-Event | The event type, for example review.created |
X-Grades-Delivery | The event id (the body's id). The same on every retry of that event: use it to drop duplicates |
X-Grades-Signature | t=<unix seconds>,v1=<hex>: the HMAC-SHA256 of <t>.<raw body> keyed with your endpoint secret |
User-Agent | Grades-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.
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));
}import hashlib
import hmac
import time
def is_from_grades(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
"""raw_body: the request body exactly as received; header: X-Grades-Signature."""
parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
if "t" not in parts or "v1" not in parts:
return False
if abs(time.time() - int(parts["t"])) > tolerance:
return False
signed = parts["t"].encode() + b"." + raw_body
expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts["v1"])<?php
// $rawBody = file_get_contents('php://input');
// $header = $_SERVER['HTTP_X_GRADES_SIGNATURE'] ?? '';
function is_from_grades(string $rawBody, string $header, string $secret, int $tolerance = 300): bool
{
$parts = [];
foreach (explode(',', $header) as $pair) {
[$key, $value] = array_pad(explode('=', $pair, 2), 2, null);
$parts[$key] = $value;
}
if (empty($parts['t']) || empty($parts['v1']) || abs(time() - (int) $parts['t']) > $tolerance) {
return false;
}
$expected = hash_hmac('sha256', $parts['t'] . '.' . $rawBody, $secret);
return hash_equals($expected, $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-Deliveryand use the review's own dates to decide what is newest. - A review you add with
POST /v1/companies/{company}/reviewsdoes not come back asreview.createdto the endpoints registered by the same key or app connection, so an integration that writes reviews does not hear its own writes.