Receive real-time event notifications via HTTP webhooks
White Circle can send HTTP POST requests to your server when specific events occur. This allows you to build custom integrations and automate workflows based on session reviews and strike-action updates.
Available Events
Setting Up Webhooks
Open Workspace Settings
Go to your Workspace Settings → Integrations page.
Add Webhook Endpoint
Click on the Webhooks integration and add your webhook URL.
Configure Events
Select which event types you want to receive notifications for.
Save
Click Save to activate the webhook.
Receiving events
Your webhook URL will receive a request for each event type you select. One request = one event.
The session.violated event includes all flagged Policies for the session.
For review_manual.* and review_auto.completed events, only the changed verdicts are included. For example, if five Policies are enabled in your Environment and our larger model (or your colleague reviewing the session) changes the verdict on two of them, we will send you only the revised policies.
strike.action.updated and strike.action.expired include the user’s current strike action state (action, action_expires_at) and strike list. Use these events to synchronize account restrictions in your app.
Error handling
Please return an HTTP 200 OK for each event you successfully receive on your Webhook URL.
Failure conditions
We consider any of these scenarios a single failure condition:
- We are unable to negotiate or validate your server’s SSL certificate.
- We wait longer than 3 seconds to receive a valid response from your server.
- We receive any other response than an HTTP 200-series response.
Retries
We’ll retry a failed request up to 3 times in a gradually increasing timetable:
- The first retry will be sent nearly immediately.
- The second retry will be attempted after 2 seconds.
- The third and final retry will be sent after 4 seconds.
Verifying requests from White Circle
With the help of signed secrets, you can verify whether requests from White Circle are authentic.
Understanding signed secrets
You can verify requests from White Circle by verifying signatures using your signing secret.
On each HTTP request that White Circle sends, White Circle adds an X-Whitecircle-Signature HTTP header (or x-whitecircle-signature — header names are meant to be case-insensitive, so the letter case should not be assumed).
The signature is created by hashing the request body with the SHA-256 function, and combining it with an HMAC signing secret. The resulting signature is unique to each request and doesn’t contain any secret information, keeping your app secure.
Request signing follows this pattern:
- Your app receives a request from White Circle.
- Your app computes a signature based on the request.
- You make sure the signature you’ve computed matches the signature on the request.
Let’s go over the recipe for this signature.
Validating a request
Grab your White Circle Signing Secret and the request body
Python
>>> whitecircle_signing_secret = 'MY_WHITECIRCLE_SIGNING_SECRET'
>>> request_body = request.text
'{"event_type":"review_auto.completed","violation":true,"internal_id":"2e9f6747-045a-4713-9a60-8c166203fce7","violations":{"4fa864e4-9af1-43b6-9fbb-33627980041f":{"violation":true,"violation_source":["text"]},"35822a7e-dc4d-4b9a-a27b-c088e8c73f1c":{"violation":false,"violation_source":["text"]},"069167bb-bda5-4b2a-b012-e3ca78944951":{"violation":false,"violation_source":["text"]}}}'Extract the timestamp header from the request
The signature depends on the timestamp to protect against replay attacks. While you’re extracting the timestamp, check to make sure that the request occurred recently. In this example, we verify that the timestamp does not differ from local time by more than five minutes.
Python
>>> import time
>>> timestamp = request.headers['X-Whitecircle-Request-Timestamp']
'1752847035'
>>> time.time() - int(timestamp) < 5 * 60
TrueConcatenate the version number, the timestamp, and the request body together, using a colon (:) as a delimiter
Python
>>> sig_basestring = 'v0:' + timestamp + ':' + request_body
'v0:1752847035:{"event_type":"review_auto.completed","violation":true,"internal_id":"2e9f6747-045a-4713-9a60-8c166203fce7","violations":{"4fa864e4-9af1-43b6-9fbb-33627980041f":{"violation":true,"violation_source":["text"]},"35822a7e-dc4d-4b9a-a27b-c088e8c73f1c":{"violation":false,"violation_source":["text"]},"069167bb-bda5-4b2a-b012-e3ca78944951":{"violation":false,"violation_source":["text"]}}}'Hash the resulting string, using the signing secret as a key, and taking the hex digest of the hash
Python
>>> import hmac
>>> import hashlib
>>> my_signature = 'v0=' + hmac.new(whitecircle_signing_secret.encode(), sig_basestring.encode(), hashlib.sha256).hexdigest()
'v0=37a8f9210398d5f370b2a10a4413ca16075d373e0c418d14c83ad71354912fbd'Compare the resulting signature to the header on the request
Python
>>> whitecircle_signature = request.headers['X-Whitecircle-Signature']
>>> hmac.compare_digest(my_signature, whitecircle_signature)
TrueDone!
That’s it! You may now proceed with processing the update.
Request schema
Headers
X-Whitecircle-Request-TimestampstringrequiredUnix timestamp (seconds) when the request was signed to protect against replay attacks.
Example:
"1752847035"X-Whitecircle-SignaturestringrequiredSignature for the request body computed as HMAC-SHA256 over 'v0:{timestamp}:{raw_body}', prefixed with 'v0='.
Example:
"v0=37a8f9210398d5f370b2a10a4413ca16075d373e0c418d14c83ad71354912fbd"
Body
application/json
event_typeenum<string>requiredType of the event
Available options:
session.violated,review_manual.in_progress,review_manual.completed,review_auto.completedviolationbooleanrequiredWhether any Policy violations were detected in the session
internal_idstringrequiredUnique internal identifier for the session
violationsobjectrequiredMap of policy IDs to their changed verdicts (only changed policies included)
Show child attributesHide child attributes
external_idstring | nullOptional external identifier provided by client
event_typeenum<string>requiredType of the event
Available options:
strike.action.updated,strike.action.expiredactionenum<string> | nullrequiredCurrent effective action
Available options:
none,throttle,warn,suspend,banaction_expires_atstring<date-time> | nullrequiredExpiration timestamp for temporary actions
strikesobject[]requiredCurrent active and historical strikes used for scoring
Show child attributesHide child attributes
strikes.created_at integer<int64>requiredstrikes.expires_at integer<int64>requiredstrikes.internal_session_id stringrequiredstrikes.points integer<int32>requiredstrikes.policy objectrequiredstrikes.reason stringrequiredstrikes.severity stringrequiredstrikes.appeal null | objectstrikes.external_session_id string | null
user_idstring | nullPrimary matched user ID
user_idsstring[]All user IDs linked to the profile
Response
Successfully received
Bad request