{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-gensail-analytics/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Webhook Payloads","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"webhook-payloads","__idx":0},"children":["Webhook Payloads"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Gensail delivers webhook payloads when algorithm processing completes. This guide documents the payload structure for both successful and failed processing outcomes."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"payload-types","__idx":1},"children":["Payload Types"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Webhooks are sent per algorithm run, and each job can have multiple algorithms configured. The webhook payload includes a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," field to indicate the outcome:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Status"},"children":["Status"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["completed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Algorithm processed successfully, extracted data included"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Algorithm processing failed, error details included"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"success-payload--status-completed-","__idx":2},"children":["Success Payload (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status: \"completed\""]},")"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When an algorithm completes successfully, the webhook payload includes the full extracted data:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n    \"status\": \"completed\",\n    \"timestamp\": \"2026-01-22T12:00:00.000000Z\",\n    \"call\": {\n        \"algorithm_run_id\": 12345,\n        \"algorithm_id\": \"appointment_scheduling\",\n        \"job_id\": 7913,\n        \"recording_url\": \"https://storage.example.com/recording.mp3\",\n        \"recording_duration\": 120.5,\n        \"contacted_date\": \"2026-01-22\",\n        \"contacted_time\": \"10:30:00\",\n        \"answered_by\": \"Sofia\",\n        \"insurance_type\": \"PPO\",\n        \"extracted_source\": \"Direct\",\n        \"call_sentiment\": \"Positive\",\n        \"call_sentiment_reason\": \"Patient scheduled appointment and expressed satisfaction\",\n        \"call_summary\": \"Patient called to schedule a dental checkup...\",\n        \"call_transcript\": \"Receptionist: Thank you for calling...\",\n        \"confidence_score\": 85.5,\n        \"annotated_transcript\": \"Receptionist: Thank you for calling <answered_by>Sofia</answered_by>...\"\n    },\n    \"data\": [\n        {\n            \"patient\": {\n                \"name\": \"John Doe\",\n                \"phone\": \"+15551234567\",\n                \"email\": \"john@example.com\",\n                \"date_of_birth\": \"1985-03-15\",\n                \"additional_spellings\": [\"Jon Doe\"]\n            },\n            \"appointment\": {\n                \"patient_type\": \"New Patient\",\n                \"visit_reason\": \"General Checkup\",\n                \"scheduled_date\": \"2026-01-25\",\n                \"scheduled_time\": \"14:00:00\",\n                \"notes\": \"Patient prefers afternoon appointments\"\n            }\n        }\n    ],\n    \"confidence\": {\n        \"overall_score\": 85.5,\n        \"flags\": [\"high_confidence\"],\n        \"breakdown\": {\n            \"call\": {\n                \"answered_by\": {\n                    \"score\": 5.0,\n                    \"max\": 5,\n                    \"confidence\": \"high\",\n                    \"agreement\": 1.0\n                }\n            },\n            \"data\": [\n                {\n                    \"patient\": {\n                        \"name\": {\n                            \"score\": 10.0,\n                            \"max\": 10,\n                            \"confidence\": \"high\"\n                        }\n                    }\n                }\n            ]\n        }\n    }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"success-payload-fields","__idx":3},"children":["Success Payload Fields"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"top-level","__idx":4},"children":["Top Level"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Always ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"completed\""]}," for successful processing"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["timestamp"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["ISO 8601 timestamp when webhook was generated"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["call"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["object"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Call-level metadata and extracted fields"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["array"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Array of patient/appointment entries"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["confidence"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["object"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Confidence scoring breakdown"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"call-section","__idx":5},"children":["Call Section"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["algorithm_run_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["integer"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unique ID of this algorithm run"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["algorithm_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Algorithm that processed this call (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["appointment_scheduling"]},")"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["job_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["integer"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Job ID in the pipeline"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recording_url"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["URL of the source audio recording"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recording_duration"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["number"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Duration in seconds"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["contacted_date"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Date when call occurred (YYYY-MM-DD)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["contacted_time"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Time when call occurred (HH:MM:SS)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["answered_by"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Name of the person who answered"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["call_transcript"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Full transcript with speaker labels"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["confidence_score"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["number"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Overall confidence score (0-100)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["annotated_transcript"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string or array"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Transcript with extraction annotations (see below)"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Additional passthrough fields from the source system may be included based on your webhook configuration."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"annotated-transcript-format","__idx":6},"children":["Annotated Transcript Format"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["annotated_transcript"]}," field contains the transcript with XML-style annotations marking extracted values. The format depends on your transcription configuration:"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"string-format-default","__idx":7},"children":["String Format (default)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["utterances"]}," is not enabled, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["annotated_transcript"]}," is a string with newline-separated lines:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n    \"annotated_transcript\": \"Receptionist: Thank you for calling. This is <answered_by>Sofia</answered_by>.\\nPatient: Hi, my name is <patient.name data-index=\\\"0\\\">John</patient.name>.\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"array-format-when-utterances-true-","__idx":8},"children":["Array Format (when ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["utterances: true"]},")"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["utterances: true"]}," is enabled in transcription settings (alongside ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["diarize: true"]},"), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["annotated_transcript"]}," becomes an array of objects with timing information:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n    \"annotated_transcript\": [\n        {\n            \"name\": \"Receptionist\",\n            \"text\": \"Thank you for calling. This is <answered_by>Sofia</answered_by>.\",\n            \"start_time\": 0.0\n        },\n        {\n            \"name\": \"Patient\",\n            \"text\": \"Hi, my name is <patient.name data-index=\\\"0\\\">John</patient.name>.\",\n            \"start_time\": 2.5\n        }\n    ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"array-entry-fields","__idx":9},"children":["Array Entry Fields"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["name"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string or null"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Speaker role (e.g., \"Receptionist\", \"Patient\"). Null for voicemails."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["text"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Utterance text with XML annotation tags"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["start_time"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["number or null"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Start timestamp in seconds. Null if alignment failed."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"edge-cases","__idx":10},"children":["Edge Cases"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Voicemail calls"]},": Speaker labels are stripped, so ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["name"]}," will be ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," for all entries:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n    \"annotated_transcript\": [\n        {\n            \"name\": null,\n            \"text\": \"Hi, this is <patient.name data-index=\\\"0\\\">Sarah</patient.name>. Please call me back.\",\n            \"start_time\": null\n        }\n    ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Alignment failure"]},": If timestamps cannot be aligned with transcript lines, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["start_time"]}," will be ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," but the array format is still used:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n    \"annotated_transcript\": [\n        {\n            \"name\": \"Receptionist\",\n            \"text\": \"Hello, dental office.\",\n            \"start_time\": null\n        }\n    ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"failure-payload--status-failed-","__idx":11},"children":["Failure Payload (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status: \"failed\""]},")"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When algorithm processing fails, a failure webhook is sent with error details:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n    \"status\": \"failed\",\n    \"timestamp\": \"2026-01-22T12:00:00.000000Z\",\n    \"call\": {\n        \"algorithm_run_id\": 12346,\n        \"algorithm_id\": \"appointment_scheduling\",\n        \"job_id\": 7914,\n        \"recording_url\": \"https://storage.example.com/recording.mp3\",\n        \"recording_duration\": 45.0,\n        \"contacted_date\": \"2026-01-22\",\n        \"contacted_time\": \"11:00:00\"\n    },\n    \"error\": {\n        \"stage\": \"extraction\",\n        \"message\": \"LLM failed to extract structured data from transcript\",\n        \"code\": \"EXTRACTION_FAILED\"\n    }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"failure-payload-fields","__idx":12},"children":["Failure Payload Fields"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"top-level-1","__idx":13},"children":["Top Level"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Always ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"failed\""]}," for failed processing"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["timestamp"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["ISO 8601 timestamp when webhook was generated"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["call"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["object"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Minimal call metadata (no transcript)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["object"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Error details"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"call-section-failure","__idx":14},"children":["Call Section (Failure)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The failure payload includes a minimal ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["call"]}," section for identification:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["algorithm_run_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["integer"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unique ID of the failed algorithm run"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["algorithm_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Algorithm that failed"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["job_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["integer"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Job ID in the pipeline"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recording_url"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["URL of the source audio recording"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recording_duration"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["number"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Duration in seconds (if available)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["contacted_date"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Date when call occurred"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["contacted_time"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Time when call occurred"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Note:"]}," The transcript is NOT included in failure payloads to keep them minimal."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"error-section","__idx":15},"children":["Error Section"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["stage"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Processing stage where failure occurred"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["message"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Human-readable error description"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Machine-readable error code"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"error-codes","__idx":16},"children":["Error Codes"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Code"},"children":["Code"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Stage"},"children":["Stage"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRANSCRIPTION_FAILED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["transcription"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Audio transcription failed"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["EXTRACTION_FAILED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["extraction"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["LLM failed to extract structured data"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VALIDATION_FAILED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["validation"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Extracted data failed schema validation"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PROCESSING_FAILED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["(any)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["General processing failure"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Notes:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Webhook delivery failures (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error_stage: \"publishing\""]},") do NOT trigger failure webhooks to avoid infinite loops."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Transcription failures (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error_stage: \"transcription\""]},") generate failure webhooks for each configured algorithm, even though no extraction was attempted. This ensures you're notified of all processing failures."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"handling-both-payload-types","__idx":17},"children":["Handling Both Payload Types"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your webhook endpoint should check the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," field to determine how to process the payload:"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"python-example","__idx":18},"children":["Python Example"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"from flask import Flask, request, jsonify\n\napp = Flask(__name__)\n\n@app.route('/webhook', methods=['POST'])\ndef handle_webhook():\n    payload = request.get_json()\n\n    if payload['status'] == 'completed':\n        # Process successful extraction\n        job_id = payload['call']['job_id']\n        algorithm_run_id = payload['call']['algorithm_run_id']\n        patients = payload['data']\n\n        for entry in patients:\n            patient = entry.get('patient', {})\n            appointment = entry.get('appointment', {})\n            # ... process extracted data\n\n        return jsonify({'status': 'processed'}), 200\n\n    elif payload['status'] == 'failed':\n        # Handle failure notification\n        job_id = payload['call']['job_id']\n        algorithm_run_id = payload['call']['algorithm_run_id']\n        error = payload['error']\n\n        log_error(\n            job_id=job_id,\n            algorithm_run_id=algorithm_run_id,\n            stage=error['stage'],\n            code=error['code'],\n            message=error['message']\n        )\n\n        return jsonify({'status': 'acknowledged'}), 200\n\n    return jsonify({'error': 'Unknown status'}), 400\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"nodejs-example","__idx":19},"children":["Node.js Example"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"app.post('/webhook', (req, res) => {\n    const payload = req.body;\n\n    if (payload.status === 'completed') {\n        // Process successful extraction\n        const { job_id, algorithm_run_id } = payload.call;\n        const patients = payload.data;\n\n        patients.forEach(entry => {\n            const { patient, appointment } = entry;\n            // ... process extracted data\n        });\n\n        res.json({ status: 'processed' });\n\n    } else if (payload.status === 'failed') {\n        // Handle failure notification\n        const { job_id, algorithm_run_id } = payload.call;\n        const { stage, code, message } = payload.error;\n\n        console.error(`Job ${job_id} failed at ${stage}: ${message} (${code})`);\n\n        res.json({ status: 'acknowledged' });\n    }\n});\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"webhook-delivery","__idx":20},"children":["Webhook Delivery"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Webhooks are sent per algorithm run (a job may have multiple algorithms)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Both success and failure webhooks are sent to the same configured URL"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Failed webhook deliveries are retried with exponential backoff (3 retries)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["All webhooks include ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Job-ID"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Algorithm-ID"]}," headers for routing"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"related-documentation","__idx":21},"children":["Related Documentation"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/gensail-analytics/guides/webhook-authentication"},"children":["Webhook Authentication"]}," - Verify webhook signatures"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/gensail-analytics/guides/webhook-credential-configuration"},"children":["Webhook Credential Configuration"]}," - Configure outgoing authentication"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"support","__idx":22},"children":["Support"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For questions about webhook payloads, contact ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"mailto:support@gensail.com"},"children":["support@gensail.com"]},"."]}]},"headings":[{"value":"Webhook Payloads","id":"webhook-payloads","depth":1},{"value":"Payload Types","id":"payload-types","depth":2},{"value":"Success Payload ( status: \"completed\" )","id":"success-payload--status-completed-","depth":2},{"value":"Success Payload Fields","id":"success-payload-fields","depth":3},{"value":"Top Level","id":"top-level","depth":4},{"value":"Call Section","id":"call-section","depth":4},{"value":"Annotated Transcript Format","id":"annotated-transcript-format","depth":3},{"value":"String Format (default)","id":"string-format-default","depth":4},{"value":"Array Format (when utterances: true )","id":"array-format-when-utterances-true-","depth":4},{"value":"Array Entry Fields","id":"array-entry-fields","depth":4},{"value":"Edge Cases","id":"edge-cases","depth":4},{"value":"Failure Payload ( status: \"failed\" )","id":"failure-payload--status-failed-","depth":2},{"value":"Failure Payload Fields","id":"failure-payload-fields","depth":3},{"value":"Top Level","id":"top-level-1","depth":4},{"value":"Call Section (Failure)","id":"call-section-failure","depth":4},{"value":"Error Section","id":"error-section","depth":4},{"value":"Error Codes","id":"error-codes","depth":3},{"value":"Handling Both Payload Types","id":"handling-both-payload-types","depth":2},{"value":"Python Example","id":"python-example","depth":3},{"value":"Node.js Example","id":"nodejs-example","depth":3},{"value":"Webhook Delivery","id":"webhook-delivery","depth":2},{"value":"Related Documentation","id":"related-documentation","depth":2},{"value":"Support","id":"support","depth":2}],"frontmatter":{"seo":{"title":"Webhook Payloads"}},"lastModified":"2026-03-27T16:51:42.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/gensail-analytics/guides/webhook-payloads","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}