Appearance
Webhooks
A webhook tells another system, such as your CRM, when an application is created, changed or moves to another status. SAWScore sends a signed POST with a JSON body to an address you register. The first half of this page is for the person who sets it up; the rest is for the developer of the receiving system.
Set up an endpoint
Open SAWScore → Settings and select the Webhooks tab.
Select Add a webhook. Give it a Name and the Address (URL), tick the events under Send a message when, and select Add the webhook.
The signing secret is shown. Select Copy, store it in the receiving system, then select I have stored it. It is shown only this once.
Select Send a test. The test is queued; its result appears under Last delivery after about a minute.
- 1Switch an endpoint off and on
- 2The result of the last message: select it to open the delivery log
- 3Send a test, open the log, edit, replace the secret, delete
| Rule | Detail |
|---|---|
| Address | Must start with https:// and be on the public internet. Private, local and internal addresses are refused, when you save and again before every send. No user name, password or # part. |
| How many | At most 10 webhooks per organization. |
| Secret | Stored encrypted and never shown again. Replace the secret makes a new one, shown once; the old one stops working at once. |
| Timing | Messages are sent by a task that runs every minute, so expect a delay of up to a minute. |
| Delivery log | The list button opens the newest 50 deliveries. Deliveries are kept for 30 days, at most 500 per webhook. Deleting a webhook deletes its log. |
Events
| Event | Sent when |
|---|---|
application.created | An application is created. |
application.updated | A saved change: answers, notes, tags, salesperson, co-buyer link, a re-evaluation or a restored revision. |
application.status_changed | The status changes. Carries previous_status. |
ping | You select Send a test. Its data is a message and the webhook's id and name. |
One status change produces two messages: application.status_changed and application.updated. Comments, files, share links and AI summaries produce none.
What is sent
json
{
"id": 10,
"event": "application.status_changed",
"created_at": "2026-06-01T14:40:00Z",
"organization": { "id": 14 },
"data": {
"id": 7,
"status": { "key": "preapproved", "label": "Preapproved" },
"previous_status": { "key": "pending", "label": "Pending" },
"grade": "C",
"total_score": 1295,
"final_decision": "Rate is 20.9% || Required Term || Required Down || || $345.00",
"revision_number": 2,
"customer": { "id": 7, "first_name": "Farah", "last_name": "Qureshi", "crm_id": "CRM-1055", "external_ids": { "dealStage": "Working" } },
"salesperson": { "id": 4, "name": "Nora Castillo" },
"lot": { "id": 2, "name": "Eastside" },
"ruleset": { "id": 2, "name": "Default", "version": 2 },
"created_at": "2026-05-28T15:10:00Z",
"updated_at": "2026-06-01T14:40:00Z"
}
}previous_status is present on status changes only. grade, total_score, final_decision, crm_id, salesperson, lot and ruleset can be null. external_ids holds the customer's outside ids and, as dealStage, the deal stage. Times are UTC.
Never sent: the answers on the application (so no Social Security number, income or address), the co-buyer, notes, annotations, comments, files and tags.
Headers and signature
| Header | Value |
|---|---|
Content-Type | application/json |
User-Agent | SAWScore-Webhooks/1 |
X-SawScore-Event | The event name. |
X-SawScore-Delivery | The delivery id, the same as id in the body and the same on every retry. |
X-SawScore-Timestamp | Unix seconds when this attempt was signed. It changes on a retry; the body does not. |
X-SawScore-Signature | sha256= and 64 lower-case hex characters. |
The signature is HMAC-SHA256 over the timestamp, a dot and the raw body, with the whole secret (including whsec_) as the key. Check it on the body exactly as received, before parsing the JSON:
php
function is_from_sawscore(string $secret, string $timestamp, string $signature, string $rawBody): bool
{
$t = trim($timestamp);
if (!preg_match('/^\d{1,12}$/', $t) || !preg_match('/^sha256=([0-9a-f]{64})$/', trim($signature), $m)) {
return false;
}
if (abs(time() - (int) $t) > 300) { // more than 5 minutes from your clock: refuse (replay)
return false;
}
return hash_equals(hash_hmac('sha256', $t . '.' . $rawBody, $secret), $m[1]);
}
$ok = is_from_sawscore(
$secret,
$_SERVER['HTTP_X_SAWSCORE_TIMESTAMP'] ?? '',
$_SERVER['HTTP_X_SAWSCORE_SIGNATURE'] ?? '',
file_get_contents('php://input')
);Answer with any 2xx status within 10 seconds. Only the first 4 KB of your answer are read.
Retries and switch-off
- Anything but a
2xxis a failure: an error status, a timeout, or a redirect (redirects are not followed). - A failed message is tried again after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours: 6 attempts in all, then it is given up and shows as Failed.
- Delivery is at least once and in no fixed order. Use
X-SawScore-Deliveryto ignore a repeat, andrevision_numberorupdated_atto ignore an older state. - After 15 failed attempts in a row the webhook is switched off, and what it still had queued fails. Everyone with the settings permission gets a notification in the bell: "Webhook “…” was switched off". Fix the receiver, then switch the webhook on again; the count starts over.
Messages you may see
| You see | It means |
|---|---|
| "The address must start with https://" | Plain http:// is not accepted. |
| "This address is not on the public internet. Private, local and internal addresses are not allowed." | The host resolves to a private or local address. |
| "The host name of this address could not be found" | The name does not resolve. Check the spelling. |
| "Choose at least one event" | No event is ticked. |
| "An organization can have at most 10 webhooks. Delete one first." | The limit is reached. |
| "This webhook is switched off. Switch it on to send a test." | Send a test needs an active webhook. |
| "HTTP 3xx: the address answered with a redirect, which is not followed" (in the log) | Register the final address. |