Webhook events
Get a signed message the moment something happens, instead of checking 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
GET/webhookswebhooks:manage
POST/webhookswebhooks:manage
DELETE/webhooks/{id}webhooks:manage
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.
Example request (example values)
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"