> For the complete documentation index, see [llms.txt](https://sonic-ai-works.gitbook.io/sonic-networks-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sonic-ai-works.gitbook.io/sonic-networks-docs/api-reference/callbacks-and-webhooks.md). # Callbacks & webhooks Preview callback and webhook processing contract for authentication, replay protection, out-of-order stages, durable receipts and idempotent terminal financial effects. **Status:** `Preview / Development` Provider callbacks and internal webhooks are treated as untrusted network input until authenticated and validated. They may be duplicated, delayed, retried, partially populated or delivered out of order. ## Provider boundary Browser clients do not directly settle provider callback state. ``` provider → public callback endpoint → signature/authentication validation → durable callback receipt → operation resolver → monotonic state merge → terminal verification → financial transition → reconciliation / event publication ``` Provider credentials, webhook secrets and diagnostic payloads remain server-side. ## Processing algorithm 1. Authenticate and validate the callback using the configured provider strategy. 2. Reject unsupported content type, oversized payloads or malformed schemas before domain mutation. 3. Resolve the SONIC internal operation and stable asset/track identity. 4. Persist callback receipt identity, provider event identity, receive time and payload fingerprint for audit/replay handling. 5. Detect exact duplicates and return the existing processing result where possible. 6. Compare incoming stage/completeness with stored state. 7. Merge fields that add information; never erase completed/non-null results with earlier partial data. 8. Protect terminal states from regression caused by delayed earlier-stage callbacks. 9. Execute credit settlement/release and other terminal economic transitions idempotently only after the terminal provider result is verified. 10. Publish downstream events through a durable outbox/event mechanism where required. Processing the same callback twice must produce the same stored state and financial outcome as processing it once. ## Stage monotonicity Callbacks do not receive authority merely because they arrived later in wall-clock time. Domain progression follows provider stage policy and stored completeness. Example: ``` QUEUED → PROCESSING → PARTIAL → COMPLETED ``` A late `PROCESSING` callback must not overwrite a stored `COMPLETED` result. Terminal failure handling must likewise avoid erasing already verified terminal success unless the provider contract explicitly supports a stronger corrective event and SONIC reconciliation policy authorizes it. ## Partial asset merge When providers return tracks/assets independently, merge by stable provider/SONIC asset identity. Missing fields in a partial callback do not mean previously stored values should become null. ``` incoming null / absent ≠ instruction to erase authoritative stored result ``` ## Authentication and replay protection Use the strongest provider mechanism available, such as signed requests, HMAC verification, timestamp windows, nonce/event IDs or provider-specific authenticated fetch-back. If a provider offers no cryptographic callback authentication, terminal state should be confirmed through a trusted server-to-server provider query before high-value settlement when practical. Callback URLs, secrets and reconciliation credentials must never be embedded in browser code. ## Response timing Webhook endpoints should acknowledge only after the callback is durably accepted for processing. Expensive downstream work should be decoupled when possible so provider retry behavior does not depend on long request execution. A `2xx` response means the callback was accepted according to the endpoint contract; it does not necessarily mean all downstream settlement/reconciliation has completed. ## Observability Persist enough server-side metadata to investigate: * provider event ID; * internal operation ID; * callback fingerprint; * receive/processed timestamps; * accepted/rejected reason; * previous and resulting stage; * duplicate/replay state; * terminal credit transition identity; * reconciliation status. Sensitive provider payload fields must be redacted from public logs and responses. ## Canonical invariant ``` authenticated callback + durable receipt + replay protection + monotonic state merge + terminal result verification + idempotent economic transition = valid callback processing ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://sonic-ai-works.gitbook.io/sonic-networks-docs/api-reference/callbacks-and-webhooks.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.