Skip to content
ReferenceForOrganization adminDeveloper⏱ About 10 min
Before you start:
  • The permission for statuses tags lots salespeople and settings
  • An HTTPS address on the receiving system

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 ​

  1. Open SAWScore → Settings and select the Webhooks tab.

  2. 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.

  3. 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.

  4. Select Send a test. The test is queued; its result appears under Last delivery after about a minute.

    1. 1Switch an endpoint off and on
    2. 2The result of the last message: select it to open the delivery log
    3. 3Send a test, open the log, edit, replace the secret, delete
RuleDetail
AddressMust 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 manyAt most 10 webhooks per organization.
SecretStored encrypted and never shown again. Replace the secret makes a new one, shown once; the old one stops working at once.
TimingMessages are sent by a task that runs every minute, so expect a delay of up to a minute.
Delivery logThe 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 ​

EventSent when
application.createdAn application is created.
application.updatedA saved change: answers, notes, tags, salesperson, co-buyer link, a re-evaluation or a restored revision.
application.status_changedThe status changes. Carries previous_status.
pingYou 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 ​

HeaderValue
Content-Typeapplication/json
User-AgentSAWScore-Webhooks/1
X-SawScore-EventThe event name.
X-SawScore-DeliveryThe delivery id, the same as id in the body and the same on every retry.
X-SawScore-TimestampUnix seconds when this attempt was signed. It changes on a retry; the body does not.
X-SawScore-Signaturesha256= 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 2xx is 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-Delivery to ignore a repeat, and revision_number or updated_at to 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 seeIt 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.