Webhooks and callbacks

Abi integrations use server-to-server webhooks for asynchronous service events and postMessage callbacks for agreed embedded browser flows.

Webhook handling

1. Register an endpoint for each event through the webhook operation.
2. Send an eventList containing one { name, url } entry for every event your integration handles.
3. Retrieve the authenticated partner’s registered events with GET /webhook.
4. Stop a single event subscription with PATCH /webhook/event/{name}/unsubscribe; this API does not provide a delete-webhook operation.
5. Authenticate or validate every delivery using the mechanism defined in your partner contract.
6. Return a successful response quickly and move slow work to an asynchronous queue.
7. Make processing idempotent because deliveries can be retried.
8. Log event identifiers and outcomes without logging sensitive payloads.

Use the format-event operation only where your integration contract requires it. It returns a requested representation of a configured common event; it is not the delivery envelope for Health Navigator conversation events. The event catalog below and the Health Navigator guide describe the available event names and delivery payloads.

The format-event request requires an event type. Include userId and/or caseId only when you need the corresponding user or consultation data in the response.

Available webhook events

The events available to an integration depend on its enabled products and partner contract. Subscribe only to the events your endpoint handles. The webhook configuration API validates each event name as a non-empty string; it does not enforce this product catalog.

Event	Delivered when	Applicable services
caseClaimCanceled	A claimed case is cancelled and becomes available to the rest of the healthcare-professional pool.	Consultation, form-based prescription, video consultation
caseClaimed	A healthcare professional claims a case.	Consultation, form-based prescription, video consultation
caseCanceled	A user, healthcare professional, or administrator cancels a case.	Consultation, form-based prescription, video consultation
caseClosed	A case closes, with or without a rating.	Consultation, form-based prescription, video consultation
caseSkipped	A healthcare professional skips a case.	Consultation, form-based prescription, video consultation
prescriptionCreated	A prescription is created. This is commonly used to notify partners integrated with other providers.	Video consultation, form-based prescription
prescriptionDeliveryAsked	The user is asked for a delivery address for their medication.	Video consultation
prescriptionDeliveryOrPharmacyAsked	The user is asked for either a medication delivery address or the pharmacy to receive the prescription.	Video consultation
prescriptionFileReady	A prescription file is created.	Video consultation, form-based prescription
prescriptionPatientAddressAsked	The user is asked for their address.	Video consultation
prescriptionPharmacySelected	The user selects the pharmacy to receive the prescription.	Video consultation
prescriptionResolved	A form-based prescription is resolved.	Form-based prescription
questionAccepted	A case becomes available to a pool of healthcare professionals.	Consultation, form-based prescription, video consultation
questionResolved	A healthcare professional answers a case.	Consultation, form-based prescription, video consultation
videoCallFinished	The video call for a video-consultation case ends.	Video consultation
videoCallStarted	The video call for a video-consultation case starts.	Video consultation
videoConsultationResolved	A video consultation is resolved.	Video consultation
conversationReplied⁺	Health Navigator replies to a message in an open conversation.	Health Navigator
conversationClosed⁺	A Health Navigator conversation is closed manually or after inactivity.	Health Navigator

⁺ Health Navigator events use their own v2 conversation envelope, not the common format-event response.

Event payloads

Generic events

All events in the catalog other than the Health Navigator events use the same common envelope. Fields that do not apply to an event are omitted.

Attribute	Description
type	The event name, such as questionResolved or prescriptionCreated.
caseId	The consultation or case identifier associated with the event, when applicable.
userId	The Abi user identifier associated with the event, when applicable.

{
  "type": "questionResolved",
  "caseId": "case12345",
  "userId": "abi12345"
}

Health Navigator events

Navigator events use a conversation envelope with stable conversation and message identifiers. Expand an event below to see its attributes and a representative payload.

• conversationReplied

  Payload attributes

  Attribute	Description
  type	Always conversationReplied.
  userId	The Abi user identifier associated with the conversation.
  conversationInfo	The conversation identifier and current status.
  message	The assistant message, including its identifiers, role, timestamps, protocol version, and ordered content parts.

  Example

  {
    "type": "conversationReplied",
    "userId": "abi12345",
    "conversationInfo": {
      "id": "t745xsvazdw1my0rhdw3wnfp",
      "status": "OPEN"
    },
    "message": {
      "messageId": "01HK8GGQX9QXDZ9W7H9N6K8ABC",
      "conversationId": "01HK8GGQ123456789ABCDEFGHI",
      "role": "assistant",
      "content": {
        "type": "message",
        "parts": [
          {
            "type": "text",
            "text": "Please describe your symptoms or ask any health-related questions you have."
          }
        ]
      },
      "parentMessageId": "01HK8GGQX9QXDZ9W7H9N6K8XYZ",
      "createdAt": "2024-01-15T10:30:02.000Z",
      "updatedAt": "2024-01-15T10:35:02.000Z",
      "protocolVersion": "1.0.0"
    }
  }

• conversationClosed

  Payload attributes

  Attribute	Description
  type	Always conversationClosed.
  userId	The Abi user identifier associated with the conversation.
  conversationInfo	The conversation identifier and final status. No message is included.

  Example

  {
    "type": "conversationClosed",
    "userId": "abi12345",
    "conversationInfo": {
      "id": "t745xsvazdw1my0rhdw3wnfp",
      "status": "CLOSED"
    }
  }

Browser callbacks

Browser callbacks are client-side events for embedded GoApp experiences, rather than server-to-server webhooks. See GoApp browser events for the postMessage listener, event handling, and origin-validation requirements. Browser callbacks must never carry partner credentials.