Webhook events
Get a signed message the moment something happens, instead of checking the API.
In short
A webhook is a message our server sends to yours when something happens, such as a new review or a reply, so you don't have to keep asking the API. Each message is signed so you can check it came from us, and failed deliveries are retried. Events can be managed in the business portal or through the API.
Events
| Field | Type | Description |
|---|---|---|
| review.created | event | A new review is published |
| review.updated | event | A review is edited, verified, resolved or restored |
| review.removed | event | A review is removed or hidden by moderation |
| reply.created | event | Someone on your team replies |
| invitation.sent | event | An invitation is sent |
| invitation.completed | event | An invited customer writes a review |
| score.changed | event | Your ProofScore changes |
| proof.requested | event | A proof request is opened or decided |
Delivery
- HTTPS POST with a JSON body to a public HTTPS address (port 443 or 8443).
- Respond with 2xx within 10 seconds.
- 8 retries over about 24 hours (1 min, 5 min, 15 min, 30 min, 1 h, 2 h, 6 h, 14 h after each failure).
- Paused after 3 days of failures; the owner is emailed and resumes it after fixing it.
- Events can arrive more than once or out of order: use the event id to ignore repeats.
- Every attempt, with the request and response, is in the delivery log for 30 days.
Signature
Every request has a Proofwell-Signature header: t = the time (Unix seconds), v1 = HMAC-SHA256 of the time, a dot and the raw body, keyed with your signing secret, as hex. Check it before trusting the message and ignore messages older than 5 minutes. After you rotate the secret, the old one also signs (a second v1) for 24 hours.
Endpoints
Add endpoints in the business portal (Settings → Developers → Webhooks) or with a key that has webhooks:manage. Up to 10 per company. The signing secret is shown once, when the endpoint is created.
POST /your/endpoint HTTP/1.1
Content-Type: application/json
User-Agent: Proofwell-Webhooks/1.0
Proofwell-Signature: t=1790234532,v1=5d8c…
Proofwell-Event: review.created
Proofwell-Delivery: dlv_2841
Proofwell-Attempt: 1
{
"id": "evt_3kq9ZyC1b2x7Lm0P",
"type": "review.created",
"created_at": "2026-09-24T02:42:08.000Z",
"data": {
"review_id": "rev_1042",
"business_id": "biz_example-coffee",
"stars": 5,
"proof": "transaction",
"language": "en"
}
}# Every webhook request carries a Proofwell-Signature header:
Proofwell-Signature: t=1790234532,v1=5d8c…
# 1. Take t and every v1 value from the header.
# 2. HMAC-SHA256 of "<t>.<raw body>" with your signing secret, as hex.
# 3. Trust the message only if one v1 matches and t is less than 5 minutes old.
echo -n "$T.$RAW_BODY" | openssl dgst -sha256 -hmac "$PROOFWELL_WEBHOOK_SECRET"