Webhooks

Overview

The Formi API Webhook enables downstream systems (e.g., CRM, dashboards, email notifiers) to receive real-time updates about the state of interactions handled by the Formi platform. This includes events from queue assignment to post-call analysis and dispatch.

Formi sends these events via HTTP POST to a configured webhook URL associated with each outlet.

Supported Event Types

All the possible events are defined below. Some events are system-internal and others are used for external webhook triggering.

Event Type	Description
`queue_added`	Interaction has been added to the processing queue
`queue_updated`	Queue status or position has been updated
`queue_cleared`	Queue has been cleared for this interaction
`interaction_trigger`	Pre-processing trigger before call start
`interaction_start`	Interaction has started (e.g., bot/call begins)
`interaction_end`	Interaction has ended (normally or abnormally)
`interaction_analysed`	Post-interaction analysis has been completed (e.g., sentiment, outcome)
`post_interaction_dispatched`	Final data (e.g., metadata, transcript) has been dispatched to external systems
`post_call_end`	Post-dispatch cleanup/processing has finished (internal use)

Webhook Behavior

HTTP Method: POST

Timeout: 30 seconds per request

Retries: Up to 3 attempts with exponential backoff (1s → 2s → 4s)

Response Storage: Webhook responses (status code, headers, content) are saved in the interaction's metadata

Delivery: Non-blocking; events are sent sequentially, but failure in one does not block others

If the webhook fails after 3 retries, it is logged and flagged internally for manual follow-up.

Webhook Request Payload

Each POST request includes the following structure:

{
  "latest_event": "post_interaction_dispatched",
  "status": "ended",
  "data_to_publish": {
    "interaction_id":12354,
    "occasion": null,
    "customer_phone_number": null,
    "customer_name": null,
    "channel": null,
    "call_type": null,
    "enquiry_type": null,
    "enquiry_details": null,
    "timestamp_reservation": null,
    "call_status": null,
    "stakeholder_phone_who_picked": null,
    "is_manager_call": null,
    "booking_metadata": null,
    "call_transcript": [],
    "requirements": null
  }
}

latest_event: One of the values from the LatestEvent enum indicating the current state update.

status: Status of the interaction (e.g., ended, queued, in_progress).

data_to_publish: Context-specific data. Its structure varies by event , but always includes the interaction_id.

Webhook Response

Formi expects a 2xx status code within 30 seconds. If this is not received, the webhook is retried up to 3 times. The final failure is recorded and appended to interaction.interaction_metadata["outlet_webhook_response"].

Example Response:

{
  "status": "success",
  "message": "Webhook received and acknowledged."
}

Example Integration Flow

Developer Notes

You can inspect the webhook response later via the Interaction Details API

Currently the same webhook as the post_call webhook is used for the events. This means if the agent is already configured for post call webhooks , then this process needs to be only setup on the webhook consumer's end. Refer the Webhook Configuration for more details.

Overview#

Supported Event Types#

Webhook Behavior#

Webhook Request Payload#

Webhook Response#

Example Integration Flow#