Webhook Deliveries Are Not Arriving

Suki sends Ambient, Form filling, standalone E/M Coding, and CKG ingestion 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

Only HTTP 200 counts as delivered. When your server is unavailable, takes longer than 30 seconds, or returns 5xx, 408, or 429, Suki retries the delivery. Any other status code, including other 4xx codes and 201 or 204, is treated as a permanent failure and is not retried. For the full rules, see Retries and duplicate deliveries. 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

If signature verification fails, return 4xx and stop. A check on the age of generated-at is optional. If you add one, allow more than three minutes, because Suki’s immediate retries resend the same generated-at value. A window of two minutes or less can reject real retries.

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 or 5xx, or takes longer than 30 seconds, can look like “nothing arrived” in your product logs even though Suki sent the webhook. Suki retries after 5xx and timeouts, but not after most 4xx codes.

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