Receiving deliveries

When a subscribed trigger fires, Olira creates a delivery: one send to one destination. Webhooks receive a signed JSON POST; email destinations receive a message. Every attempt is recorded in the delivery ledger, which you can open in the Console (Outbound actions) or read with the SDK.

Payload envelope

Your webhook endpoint receives a fixed envelope. The same JSON is payload on a delivery when you fetch it from the SDK:

{
  "id": "del_123",
  "type": "patient.state.changed",
  "created": "2026-08-12T09:14:05Z",
  "api_version": "2026-08-01",
  "data": { "...": "..." }
}

type is the trigger you subscribed to. On the ledger record the SDK returns, that field is called trigger; in the body your endpoint parses, it is type. data holds ids and counts for that trigger, not clinical field values:

Trigger	`data` fields
`patient.state.changed`	`event_log_id`, `log_type`, `changed_paths`, `change_count`, `coalesced_count` (present when several updates for the same patient were folded into one delivery)
`log.no_state_change`	`event_log_id`, `log_type`
`org.mapping.failed`	`source_subtype`, `error_code`
`ingestion.completed` / `ingestion.failed`	`job_id`, `status`, `patient_count`, `record_count`, `failure_summary` (present only on partial failures)

Verifying the signature

Every webhook delivery carries an Olira-Signature header: t=<unix_ts>,v1=<hex_hmac>. Recompute it with your destination’s signing secret and compare; this proves the request came from Olira and was not altered in transit. Reject a missing or malformed timestamp, one too far in the past (replay), or one unreasonably far in the future (clock skew or forgery) before checking the signature at all. During secret rotation the header carries two v1= entries; check if any matches, don’t assume there’s exactly one. The timestamp is fresh on every attempt, including retries.

import hashlib
import hmac
import time


def verify_signature(secret: str, header: str, raw_body: bytes, *, max_skew_seconds: int = 300) -> bool:
    fields = dict(part.split("=", 1) for part in header.split(",") if part.startswith("t="))
    try:
        timestamp = int(fields["t"])
    except (KeyError, ValueError):
        return False
    if abs(time.time() - timestamp) > max_skew_seconds:
        return False
    signatures = [part.split("=", 1)[1] for part in header.split(",") if part.startswith("v1=")]
    signed_payload = f"{timestamp}.".encode() + raw_body
    expected = hmac.new(secret.encode(), signed_payload, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(expected, sig) for sig in signatures)

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

static bool VerifySignature(string secret, string header, byte[] rawBody, int maxSkewSeconds = 300)
{
    var parts = header.Split(',');
    var tPart = parts.FirstOrDefault(p => p.StartsWith("t="));
    if (tPart is null || !long.TryParse(tPart.Substring(2), out var timestamp))
        return false;
    if (Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - timestamp) > maxSkewSeconds)
        return false;

    var signatures = parts.Where(p => p.StartsWith("v1=")).Select(p => p.Substring(3));

    using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
    var signedPayload = Encoding.UTF8.GetBytes($"{timestamp}.").Concat(rawBody).ToArray();
    var expected = Convert.ToHexString(hmac.ComputeHash(signedPayload)).ToLowerInvariant();

    return signatures.Any(sig => CryptographicOperations.FixedTimeEquals(
        Encoding.UTF8.GetBytes(expected), Encoding.UTF8.GetBytes(sig)));
}

Rotate the secret when you need to; the old one stays valid for 24 hours so an in-progress rotation on your side never drops a delivery. rotate_action_destination_secret returns the new secret once, the same way create does.

Retries and the ledger

Failed webhook deliveries retry automatically, then stop if they keep failing. A destination that fails long enough is auto-disabled (20+ consecutive failures over 72 hours or more); re-enable it before you expect new sends. Every attempt is a row in the delivery ledger: pending or sending, delivered, retrying, dead-lettered, skipped, or buffered (waiting for that destination’s daily digest — that can be close to a day, not a few minutes). List and open deliveries in the Console, or with list_action_deliveries and get_action_delivery (the latter includes the exact JSON that was sent). redeliver_action_delivery resends the same body as the original, not a newly generated one. That works for up to 30 days. If the destination is disabled, re-enable it first (HTTP 409 otherwise).

Get started

Send data

Read data

Outbound actions

Console

Receiving deliveries

Payload envelope

Verifying the signature

Retries and the ledger

​Payload envelope

​Verifying the signature

​Retries and the ledger

Payload envelope

Verifying the signature

Retries and the ledger