Webhook Deliveries Are Not Arriving

Suki sends Ambient and Form filling completion (and related) notifications as an HTTPS POST to the callback URL on your partner record. If your app never sees events, check reachability, TLS, a handler that returns non-200 (or takes too long), or HMAC verification that rejects the request before you log it. Dictation does not send completion webhooks. Your app gets Dictation text on the live WebSocket.

Endpoint requirements

Your callback URL must:

Accept POST over HTTPS with TLS 1.2 or higher (Suki does not send webhooks to HTTP URLs)
Be publicly reachable (no localhost or private IPs in production)
Respond with HTTP 200 (“OK”) within 30 seconds

If delivery fails (server unavailable, response time exceeds 30 seconds, or a non-200 status), Suki retries the push up to four more times, for a total of 5 attempts. You cannot register or change the callback URL through a self-service API. Share it during Partner onboarding so Suki stores it on your partner record with your secret key.

Verify the request signature

Suki signs each notification. Verify before you parse JSON.

Component	Role
Partner secret key	HMAC key from onboarding (server-side only)
`generated-at` header	Unix time in milliseconds when Suki built the request
Raw body	Exact bytes or string Suki sent (no pretty-print, trim, or re-serialize)
Signed string	`generated-at` + `:` + raw body
`X-API-Key` header	Expected hex HMAC-SHA-256 digest

Reject requests where generated-at is older than two minutes to prevent replay attacks. If signature verification fails, return 4xx and stop.

Pseudocode

raw_body = read request body as received (string or bytes)
timestamp = request header "generated-at" exactly as sent
message = timestamp + ":" + raw_body

expected_signature_hex = request header "X-API-Key"
computed_signature_hex = hex( HMAC_SHA256(key = secret_key, data = message) )

if not constant_time_equal(computed_signature_hex, expected_signature_hex):
    return 401 or 400
# else: parse JSON and continue

Read the raw body before JSON parsing. Middleware that auto-parses JSON first changes bytes and breaks HMAC verification.

Fix

Confirm the Registered HTTPS URL

Match the path Suki stored on your partner record. Confirm the endpoint is publicly reachable over HTTPS with TLS 1.2 or higher.

Verify HMAC on the Raw Body

Compute HMAC-SHA-256 over generated-at + : + raw body with your partner secret. Compare to X-API-Key with a constant-time compare. See Signature verification.

Return 200 Quickly

After a valid signature, return HTTP 200 (“OK”) so Suki treats the notification as delivered. Do follow-up API or database work after you acknowledge.

Log Rejected Requests

Log missing headers, signature mismatches, and non-200 responses. A handler that returns 4xx/5xx or exceeds 30 seconds can look like “nothing arrived” in your product logs even though Suki retried.

Trigger a Known Session Event

Complete an Ambient or Form filling session that should emit a webhook. Dictation workflows do not send completion webhooks.

Return 200 after you receive and validate the webhook. That tells Suki the notification was delivered.

Next steps

Signature verification - HMAC steps, headers, and code samples Webhook overview - Push delivery, endpoint rules, and retries Build a webhook notification receiver - End-to-end HTTPS receiver tutorial Webhook configuration - Register the callback URL during onboarding Form filling session returns no results - Use webhooks when the browser closes early

​Endpoint requirements

​Verify the request signature

​Fix

​Next steps

Endpoint requirements

Verify the request signature

Fix

Next steps