> ## Documentation Index
> Fetch the complete documentation index at: https://developer.suki.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook Deliveries Are Not Arriving

> Debug missing partner webhook POSTs with HTTPS, HMAC verification, and HTTP 200 responses

Suki sends Ambient and Form filling completion (and related) notifications as an HTTPS <Badge color="blue" size="sm">POST</Badge> 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 <Badge color="blue" size="sm">POST</Badge> 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](/documentation/get-started/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 |

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

**Pseudocode**

```text theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
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
```

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

## Fix

<Steps>
  <Step title="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.
  </Step>

  <Step title="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](/documentation/webhook/signature-verification).
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Trigger a Known Session Event">
    Complete an Ambient or Form filling session that should emit a webhook. Dictation workflows do not send completion webhooks.
  </Step>
</Steps>

<Note>
  Return **200** after you receive and validate the webhook. That tells Suki the notification was delivered.
</Note>

## Next steps

<Icon icon="file-lines" iconType="solid" /> **[Signature verification](/documentation/webhook/signature-verification)** - HMAC steps, headers, and code samples

<Icon icon="file-lines" iconType="solid" /> **[Webhook overview](/documentation/webhook/overview)** - Push delivery, endpoint rules, and retries

<Icon icon="file-lines" iconType="solid" /> **[Build a webhook notification receiver](/documentation/tutorials/webhook-notification-receiver)** - End-to-end HTTPS receiver tutorial

<Icon icon="file-lines" iconType="solid" /> **[Webhook configuration](/documentation/webhook/configuration)** - Register the callback URL during onboarding

<Icon icon="file-lines" iconType="solid" /> **[Form filling session returns no results](/documentation/troubleshooting/form-filling-no-results)** - Use webhooks when the browser closes early