Webhooks

Webhooks are the low-latency push counterpart to the pull change feed: instead of polling GET /api/company-data/changes, allus POSTs each person→service change to an endpoint you configure per service. Same events, same payload contents, same encryption contract.

When to use webhooks

The pull change feed and webhooks deliver the identical event stream. Choose based on latency and your infrastructure:

Both paths carry the same ciphertext values (encrypted for your service key) and the same payload shape. You can switch from polling to webhooks (or back) without changing how you decrypt or process events — but consume one channel, not both, and note that the id field means different things on each (see the delivery guarantee).

Configuring a webhook

Webhooks are configured per service in the portal (Configuration → Services → your service → Webhooks) or via the portal API (POST /api/services/{id}/webhooks). A service can have multiple webhook endpoints. Step-by-step with screenshots: Portal guides → Webhooks.

Configuration fields

Payload

allus POSTs each change to your endpoint; a field_updated / field_deleted carries the slot's state as it is when the event is delivered. The body is serialized as JSON or XML per the webhook's format. Every webhook delivery carries one change event — the same shape as a single row from the pull change feed.

The events

The event vocabulary is identical to the pull feed. The event field is one of:

Body shape

A field_updated event for a text field carries the new value inline as ciphertext (the {"_enc":1,…} wrapper, encrypted for your service key):

{
  "id": "chg-…",                      // NOT a dedup key on this channel — see Delivery guarantee
  "event": "field_updated",
  "person_user_id": "…",
  "share_code": "ABC123",             // the person's profile share code (every event; may be null)
  "slug": "work_email",               // YOUR request slug — never the person's source field
  "live": true,                       // false = a one-time / snapshot answer
  "value": "{\"_enc\":1,\"k\":\"…\",\"iv\":\"…\",\"d\":\"…\"}",  // ciphertext for the SERVICE key
  "at": "2026-06-16T13:00:00Z"
}

A field_updated for a binary field (photo / document / legal document) carries a value_url instead of value — fetch it with your client token. What comes back is either the encrypted wrapper to decrypt off-platform or the raw file bytes, depending on whether the person's source field is private; branch on Content-Type (details):

{
  "id": "chg-…",
  "event": "field_updated",
  "person_user_id": "…",
  "share_code": "ABC123",
  "slug": "id_photo",
  "live": true,
  "value_url": "https://api.allme.fyi/api/company-data/connections/{connectionId}/slots/{serviceFieldId}/file",
  "at": "2026-06-16T13:00:00Z"
}

The connection-level events (connection_created, connection_deleted) carry just id, event, person_user_id, share_code, customer_type and at — no slug or value. On connection_created, fetch the connection's provided fields from GET /api/company-data/connections/{id}. The consent events (consent_accepted / consent_declined) add the resolved slot's slug, no value. The payload is slug-keyed and never includes the person's source field_id.

A document_status_changed event is its own shape — keyed by document_id, the new status and an action, with no slug, no value and no source field. It fires when the person acts on a document or contract you issued, in-app. On a contract-flow run it ALSO fires — with no action — when a signature advances the run's signing line and the next step's copy opens as a result: that event's status is the newly-opened copy's ready_to_sign or offering.

{
  "id": "chg-…",                      // NOT a dedup key on this channel — see Delivery guarantee
  "event": "document_status_changed",
  "person_user_id": "…",
  "share_code": "ABC123",
  "document_id": "doc-…",             // the document you created via /api/company-data/documents
  "status": "active",                 // offering | ready_to_sign | active | active_but_ending | ended
  "action": "signed",                 // signed | accepted | cancelled
  "method": "biometric",              // sign audit: biometric | twofa | email | custodian (null for accept/cancel)
  "content_sha256": "…",              // SHA-256 of the signed content (null when not a signature)
  "signed_at": "2026-06-22T12:47:41Z",// when the signature was recorded (null when not a signature)
  "cancel_effective_date": "2026-07-30",// on a cancellation: when it takes effect (null otherwise)
  "sealed_at": "2026-06-22T12:47:45Z", // set once the platform seal is applied (null until sealed)
  "plain_sha256": "3b9ff1a2c4…",       // SHA-256 of the document's unencrypted PDF bytes (null on a json contract)
  "signer_first_name": "Alice",        // the latest signature's own signer evidence
  "signer_last_name": "Jansen",
  "signer_name_verified": true,        // true iff that name matched the signer's verified ID name
  "at": "2026-06-22T12:47:41Z"
}

• signed / accepted — the person signed / accepted the contract (status becomes active). On a signature the event also carries the audit inline — method, content_sha256, signed_at — so you never need a follow-up document GET.
• cancelled — the person cancelled a cancellable document/contract (status becomes active_but_ending or ended); the signature fields are null. The event carries cancel_effective_date — the date the cancellation takes effect (a future date ⇒ active_but_ending until then; today ⇒ ended) — so you know when without a GET.

The connect-request events (connection_request_accepted / connection_request_rejected) are their own slug-free shape — keyed by the request_id you got back from POST /api/company-data/connect-requests, with no slug and no value:

{
  "id": "chg-…",                          // NOT a dedup key on this channel — see Delivery guarantee
  "event": "connection_request_accepted", // or "connection_request_rejected"
  "request_id": "req-…",                  // the id POST /connect-requests returned
  "person_user_id": "…",
  "share_code": "ABC123",                 // the person's profile share code
  "at": "2026-06-22T13:00:00Z"
}

The contract-flow run events (flow_run_turn / flow_completed) are run-level and slug-free — keyed by flow_run_id, with no slug and no value. flow_run_turn adds the awaiting_party now owed a turn:

{
  "id": "chg-…",                  // NOT a dedup key on this channel — see Delivery guarantee
  "event": "flow_run_turn",       // or "flow_completed"
  "person_user_id": "…",
  "share_code": "ABC123",
  "flow_run_id": "run-…",
  "awaiting_party": "company",    // flow_run_turn only — the party now owed a turn
  "at": "2026-06-22T13:00:00Z"
}

A message_received event is its own slug-free shape — the person's message to your service, with everything you need to answer it and to acknowledge it. It fires on a person→company message only; your own sends, a broadcast included, raise no event:

{
  "id": "chg-…",                      // NOT a dedup key on this channel — see Delivery guarantee
  "event": "message_received",
  "person_user_id": "…",
  "share_code": "ABC123",
  "connection_id": "019xxxx",         // reply and acknowledge on this connection
  "message_id": "019yyyy",            // pass this as the acknowledgement boundary
  "person_public_key": "<base64 SPKI>", // encrypt your reply to it — no second key fetch needed
  "body": "{\"_enc\":1,\"k\":\"…\",\"iv\":\"…\",\"d\":\"…\"}",  // ciphertext for the SERVICE key
  "created_at": "2026-08-11T09:12:00Z",
  "at": "2026-08-11T09:12:00Z"
}

Authenticating the delivery

Your endpoint should authenticate that a request genuinely came from allus. Pick one auth_type:

Verifying the HMAC signature

For the default hmac mode, recompute HMAC-SHA256 over the raw request body (exactly the bytes received, before any JSON parsing) using your webhook's HMAC secret, then constant-time-compare the hex digest to the X-Allus-Signature header:

import hmac, hashlib

def verify(raw_body: bytes, signature_header: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header)

import { createHmac, timingSafeEqual } from "crypto";

function verify(rawBody: Buffer, signatureHeader: string, secret: string): boolean {
  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(expected), b = Buffer.from(signatureHeader);
  return a.length === b.length && timingSafeEqual(a, b);
}

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
)

func verify(rawBody []byte, signatureHeader, secret string) bool {
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write(rawBody)
    expected := hex.EncodeToString(mac.Sum(nil))
    return hmac.Equal([]byte(expected), []byte(signatureHeader))
}

using System.Security.Cryptography;
using System.Text;

bool Verify(byte[] rawBody, string signatureHeader, string secret) {
    using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
    var expected = Convert.ToHexString(hmac.ComputeHash(rawBody)).ToLowerInvariant();
    return CryptographicOperations.FixedTimeEquals(
        Encoding.UTF8.GetBytes(expected), Encoding.UTF8.GetBytes(signatureHeader));
}

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.security.MessageDigest;

boolean verify(byte[] rawBody, String signatureHeader, String secret) throws Exception {
    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(new SecretKeySpec(secret.getBytes(), "HmacSHA256"));
    StringBuilder sb = new StringBuilder();
    for (byte b : mac.doFinal(rawBody)) sb.append(String.format("%02x", b));
    return MessageDigest.isEqual(sb.toString().getBytes(), signatureHeader.getBytes());
}

function verify(string $rawBody, string $signatureHeader, string $secret): bool {
    $expected = hash_hmac('sha256', $rawBody, $secret);
    return hash_equals($expected, $signatureHeader);
}

SDK webhook helpers

The six SDKs include webhook receiver helpers so you never hand-roll the verification or decryption. All secrets and keys come from your config.json — the helpers take no key or secret arguments. The SDK verifies each delivery against whichever auth_type you set on the webhook — put the matching field in your config (at most one): HMAC webhooks/webhook_secret, webhook_bearer_token, webhook_basic {"username","password"}, webhook_header {"name","value"}, or webhook_auth_none. Two or more → ConfigError. For HMAC, the delivery's X-Allus-Webhook-Id header selects that webhook's secret.

A complete receiver, in each language:

from flask import Flask, request
from allus_company_data import Client, WebhookError

app = Flask(__name__)
client = Client.from_config("config.json")

@app.post("/allus/webhook")
def webhook():
    try:
        change = client.handle_webhook(request.get_data(), dict(request.headers))
    except WebhookError:
        return ("bad signature", 401)
    # change.event, change.slug, change.value (decrypted), change.live …
    process(change)
    return ("", 200)   # MUST return HTTP 200

import express from "express";
import { Client, WebhookError } from "@allus-fyi/company-data";

const app = express();
const client = Client.fromConfig("config.json");

// handleWebhook is async: the handler must be async and await it, or the
// try/catch cannot catch a signature or parse failure.
app.post("/allus/webhook", express.raw({ type: "*/*" }), async (req, res) => {
  let change;
  try {
    change = await client.handleWebhook(req.body, req.headers);
  } catch (e) {
    if (e instanceof WebhookError) return res.sendStatus(401);
    throw e;
  }
  process(change);          // change.event, change.slug, change.value …
  res.sendStatus(200);      // MUST return HTTP 200
});

func webhook(w http.ResponseWriter, r *http.Request) {
    body, _ := io.ReadAll(r.Body)
    change, err := client.HandleWebhook(body, r.Header)
    if err != nil {           // WebhookError on a bad signature
        w.WriteHeader(http.StatusUnauthorized)
        return
    }
    process(change)           // change.Event, change.Slug, change.Value …
    w.WriteHeader(http.StatusOK)   // MUST return HTTP 200
}

app.MapPost("/allus/webhook", async (HttpRequest req) => {
    using var reader = new StreamReader(req.Body);
    var body = await reader.ReadToEndAsync();
    var headers = req.Headers.ToDictionary(h => h.Key, h => (string)h.Value!);
    try {
        var change = client.HandleWebhook(body, headers);
        Process(change);            // change.Event, change.Slug, change.Value …
        return Results.Ok();        // MUST return HTTP 200
    } catch (WebhookException) {
        return Results.Unauthorized();
    }
});

@PostMapping("/allus/webhook")
ResponseEntity<Void> webhook(@RequestBody byte[] body,
                             @RequestHeader Map<String,String> headers) {
    try {
        Change change = client.handleWebhook(body, headers);
        process(change);                       // change.event, change.slug …
        return ResponseEntity.ok().build();    // MUST return HTTP 200
    } catch (WebhookException e) {
        return ResponseEntity.status(401).build();
    }
}

$client = Client::fromConfig('config.json');

// in your route handler:
$raw = file_get_contents('php://input');
try {
    $change = $client->handleWebhook($raw, getallheaders());
    process($change);          // $change->event, $change->slug, $change->value …
    http_response_code(200);   // MUST return HTTP 200
} catch (WebhookError $e) {
    http_response_code(401);
}

The account-key envelope (encrypt_payload)

With encrypt_payload enabled, allus wraps the entire serialized body in an extra encryption layer keyed to your company account public key (not the service key). This protects the payload metadata in transit beyond TLS. The wrapper is the same {"_enc":1,"k","iv","d"} shape:

• A random AES-256 key is RSA-OAEP-wrapped to your account public key (k), and the body is AES-256-GCM-encrypted under it (iv + d).
• You decrypt with the account private key — the PEM you download from portal → Settings → Account key (GET /api/account-key). The SDK reads it from account_private_key + account_passphrase in your config and unwraps automatically inside parseWebhook / handleWebhook.

The account-key envelope is independent of the auth mode — you can combine HMAC signing and encrypt_payload on the same webhook.

Delivery, health & recovery

Deliveries are ordered per webhook (one in-flight POST at a time, so connection_created always arrives before that connection's first field_updated). Each endpoint has a health state — running, bad, or unknown — and a self-healing circuit-breaker.

1. Healthy (running): allus POSTs each event as it happens. Your endpoint returns 200.
2. A delivery fails (non-200 / connection error): the webhook flips to bad. Its pending and subsequent events are parked in the durable backlog (a company_data_changes row tagged with the webhook id) instead of being pushed. Nothing is lost.
3. 10-minute grace, then probe: the backlog is the only retry mechanism — there is no per-item exponential backoff and no dead-letter queue. After 10 minutes the webhook goes unknown and allus probes by delivering the oldest backlog row.
4. Recovery: if the probe returns 200, the webhook returns to running and the entire backlog is replayed in original (FIFO) order, then cleared. If the probe fails, it stays bad and the 10-minute cycle repeats.

Delivery guarantee — effectively unique, rarely replayed

Each queued event is POSTed once: your 200 acks it and it is dropped. Anything else — a non-200, a timeout, a connection error — is never retried in place; it flushes to the backlog above and comes back through the auto-replay or your manual drain. So deliveries are effectively unique, with exactly one exception: if your endpoint processed an event but allus never saw your 200 (your response timed out, or you crashed after committing and before responding), that event is treated as failed and replayed on recovery — so you receive it again. There is no cap of two. A probe that fails leaves its backlog row in place (step 4 above), so if the replay's 200 is lost the same way, the next probe delivers that event once more. Treat this window as at-least-once and make your handler safe to run repeatedly.

Persistent failure surfaces two ways: the service Logs tab records every state transition (running→bad with the HTTP code, bad→unknown, unknown→running with the replay count) and every config change; and the stale-queue email alerts report the webhook backlog age (≥2 days → daily, ≥5 days → hourly, 7 days → the backlog is purged and the data is lost). Deleting a webhook drops its backlog — it is not moved to the pull feed, to avoid duplicate records.

Webhooks vs. push notifications

Webhooks are the only outbound channel for companies. Companies receive no FCM/APNs push notifications — those are person-side only. The portal itself is pull-based; webhooks (and the pull change feed) are how your backend learns about person→service data changes.

Next steps

• Portal guides → Webhooks — the illustrated walkthrough for configuring an endpoint.
• SDKs — install an SDK and use the receiver helpers.
• Service API → change feed — the pull alternative, same events.
• Open the service API spec ↗