> ## 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.

# Form Filling Asynchronous Notifications

> Webhook endpoint for receiving asynchronous notifications when Form filling session processing completes

Use this endpoint specification to implement a <Tooltip tip="A mechanism that allows Suki to send real-time event notifications to your application's server." cta="View in Glossary" href="/Glossary/w">webhook</Tooltip> endpoint in your application that receives notifications from the Suki platform.

This endpoint should be hosted by your application to receive notifications about **Form filling** <Tooltip tip="A single, time-bound instance of a Form filling visit used to capture conversation and generate structured medical form output." cta="View in Glossary" href="/Glossary/s">session</Tooltip> completion or failure.

<Note>
  Host this endpoint on your server. Suki sends a POST when Form filling processing completes or fails. The payload `session_id` is the Form filling session ID from [Create Form Filling session](/form-filling-api-reference/form-filling-sessions/create).
</Note>

Learn more about how webhooks work and how to implement your webhook endpoint in [Notification webhook for partners](/documentation/webhook/overview).

## Code examples

<Tabs>
  <Tab title="Python">
    ```python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    from flask import Flask, request, jsonify

    app = Flask(__name__)

    @app.route('/webhooks/notification', methods=['POST'])
    def handle_webhook():
        """
        Webhook endpoint for Form filling session notifications.
        Verify X-API-Key and generated-at before parsing JSON; see Signature verification guide.
        """
        # TODO: verify webhook signature (see /documentation/webhook/signature-verification)
        data = request.get_json()

        if not data:
            return jsonify({"error": "Invalid request"}), 400

        status = data.get("status")

        if status == "success":
            session_id = data.get("session_id")
            encounter_id = data.get("encounter_id")
            print(f"Form filling session {session_id} completed (encounter {encounter_id})")

            links = data.get("_links") or {}
            for link in links.get("structured_data") or []:
                print(f"  Structured data: {link.get('method')} {link.get('href')}")
            for link in links.get("status") or []:
                print(f"  Status: {link.get('method')} {link.get('href')}")

            return jsonify({"message": "Notification received"}), 200

        if status == "failure":
            session_id = data.get("session_id")
            encounter_id = data.get("encounter_id")
            error_code = data.get("error_code")
            error_detail = data.get("error_detail")
            print(
                f"Form filling session {session_id} failed (encounter {encounter_id}): "
                f"{error_code} - {error_detail}"
            )
            return jsonify({"message": "Failure notification received"}), 200

        return jsonify({"error": "Unknown status"}), 400

    if __name__ == '__main__':
        app.run(port=3000)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    import express from 'express';

    const app = express();
    app.use(express.json());

    app.post('/webhooks/notification', (req, res) => {
      // TODO: verify webhook signature (see /documentation/webhook/signature-verification)
      const data = req.body;

      if (!data) {
        return res.status(400).json({ error: 'Invalid request' });
      }

      const status = data.status;

      if (status === 'success') {
        const sessionId = data.session_id;
        const encounterId = data.encounter_id;
        console.log(`Form filling session ${sessionId} completed (encounter ${encounterId})`);

        const links = data._links ?? {};
        (links.structured_data ?? []).forEach((link: { method?: string; href?: string }) => {
          console.log(`  Structured data: ${link.method} ${link.href}`);
        });
        (links.status ?? []).forEach((link: { method?: string; href?: string }) => {
          console.log(`  Status: ${link.method} ${link.href}`);
        });

        return res.status(200).json({ message: 'Notification received' });
      }

      if (status === 'failure') {
        console.log(
          `Form filling session ${data.session_id} failed (encounter ${data.encounter_id}): ` +
            `${data.error_code} - ${data.error_detail}`,
        );
        return res.status(200).json({ message: 'Failure notification received' });
      }

      return res.status(400).json({ error: 'Unknown status' });
    });

    app.listen(3000, () => {
      console.log('Webhook server listening on port 3000');
    });
    ```
  </Tab>
</Tabs>


## OpenAPI

````yaml POST /webhooks/notification
openapi: 3.0.1
info:
  title: Suki Developer Platform
  description: This is the API Gateway for Suki Developer Platform
  contact: {}
  version: '1.0'
servers:
  - url: https://sdp.suki.ai
    description: Suki Developer Platform - Production
security: []
paths:
  /webhooks/notification:
    post:
      tags:
        - /webhooks
      summary: Spec of webhook to be hosted by External Partners.
      description: >-
        Following defines the specification to which the webhook endpoint,
        hosted to receive notifications, must conform to.

        It outlines the structure of the notification that the webhook should
        handle in case of generation success or failure
      requestBody:
        description: FailureNotification
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/controllers.FailureNotification'
        required: false
      responses:
        '200':
          description: OK
          content: {}
        '400':
          description: Bad Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/controllers.BadRequestError'
        '401':
          description: Unauthorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/controllers.AuthenticationError'
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/controllers.InternalServerError'
components:
  schemas:
    controllers.FailureNotification:
      type: object
      properties:
        encounter_id:
          type: string
          description: Id of the encounter to which the payload belongs.
          example: 29de56bc-960a-4cd5-b18f-79a798d62874
        error_code:
          type: string
          description: Error code.
          example: ERROR_CODE_TRANSCRIPTION
        error_detail:
          type: string
          description: Details of the error, if any.
          example: Error in transcription
        session_id:
          type: string
          description: Id of the session that failed.
          example: 20965414-929a-4f71-a3e5-b92bec07d086
        status:
          type: string
          example: failure
    controllers.BadRequestError:
      type: object
      properties:
        code:
          type: integer
          example: 400
        message:
          type: string
          example: invalid request
      description: Bad Request Response
    controllers.AuthenticationError:
      type: object
      properties:
        code:
          type: integer
          example: 401
        message:
          type: string
          example: invalid token
      description: Authentication Failure Response
    controllers.InternalServerError:
      type: object
      properties:
        code:
          type: integer
          example: 500
        message:
          type: string
          example: internal server error
      description: Internal Server Error Response

````