Webhook Payload Reference

This page documents the structure of webhook payloads sent by Diaform, including HTTP headers and JSON body schemas.

HTTP Headers#

Every webhook request includes the following headers:

Header	Value	Description
`Content-Type`	`application/json`	The payload is JSON-encoded
`X-Webhook-Event`	`conversation.completed`	The event that triggered the webhook
`X-Webhook-Signature`	HMAC-SHA256 hex digest	HMAC signature for verifying authenticity

conversation.completed Event#

Fired when a conversation finishes and the AI-generated summary is ready.

Example Payload#

{
  "conversation_id": "uuid",
  "agent_id": "uuid",
  "organization_id": "uuid",
  "status": "completed",
  "respondent": {
    "email": "respondent@example.com",
    "metadata": {},
    "identities": [
      {
        "type": "identifier",
        "value": "customer-123",
        "source": "owner"
      },
      {
        "type": "email",
        "value": "respondent@example.com",
        "source": "ai"
      }
    ],
    "invite_id": null
  },
  "summary": {
    "respondent_email": null,
    "respondent_identities": [
      {
        "type": "email",
        "value": "respondent@example.com"
      }
    ],
    "answers": [
      {
        "question_id": "question-1",
        "question_text": "How satisfied are you with our product?",
        "summary": "The respondent was very satisfied, especially with onboarding.",
        "sentiment": "positive",
        "confidence": "high",
        "quotes": ["The onboarding was really smooth"]
      }
    ],
    "overall_sentiment": "positive",
    "urgent_issues": [],
    "additional_insights": "The respondent mentioned interest in API access.",
    "actions_called": [
      {
        "action_type": "send_slack_message",
        "ended_conversation": false,
        "description": "Sent Slack notification for a delighted fan trigger."
      }
    ]
  },
  "completed_at": "2026-02-09T12:00:00.000Z"
}

Field Reference#

Field	Type	Description
`conversation_id`	string	Unique ID of the conversation
`agent_id`	string	The project that conducted the conversation
`organization_id`	string	Your organization ID
`status`	string	Always `"completed"` for this event
`respondent`	object	Respondent identity and metadata attached to the conversation
`respondent.email`	string or null	Best available respondent email, preferring the legacy respondent email value and then an `email` identity
`respondent.metadata`	object	Conversation metadata
`respondent.identities`	array	Visible respondent identities from invites, embeds, system collection, or AI extraction
`respondent.identities[].type`	string	Identity type, such as `email`, `name`, `identifier`, `user_id`, or `account_id`
`respondent.identities[].value`	string	Identity value
`respondent.identities[].source`	string	`owner`, `system`, or `ai`
`respondent.invite_id`	string or null	Invite ID when the conversation came from a targeted respondent link
`summary`	object or null	AI-generated conversation summary
`summary.respondent_email`	string or null	Legacy compatibility field. New AI-extracted emails are returned in `summary.respondent_identities` and `respondent.identities`.
`summary.respondent_identities`	array or null	Identities extracted from respondent messages during post-processing
`summary.respondent_identities[].type`	string	Identity type, such as `email`, `name`, `identifier`, `uuid`, `user_id`, or `account_id`
`summary.respondent_identities[].value`	string	Extracted identity value
`summary.answers`	array	Per-question structured answers
`summary.answers[].question_id`	string	Internal question ID
`summary.answers[].question_text`	string	The question text
`summary.answers[].summary`	string	AI-generated summary of the respondent's answer
`summary.answers[].sentiment`	string	`positive`, `negative`, `neutral`, or `mixed`
`summary.answers[].confidence`	string	`high`, `medium`, or `low`
`summary.answers[].quotes`	`string[]` or null	Direct quotes from the respondent
`summary.overall_sentiment`	string	Overall conversation sentiment
`summary.urgent_issues`	`string[]`	Critical issues flagged by the AI
`summary.additional_insights`	string	Extra context not covered by questions
`summary.actions_called`	array	Automation or tool actions recorded during the conversation
`summary.actions_called[].action_type`	string	Type of action
`summary.actions_called[].ended_conversation`	boolean	Whether the action ended the conversation
`summary.actions_called[].description`	string	Human-readable action description
`completed_at`	string	ISO 8601 timestamp of when the conversation completed

Sentiment Values#

positive: The response expresses satisfaction or positive feedback
negative: The response expresses dissatisfaction or negative feedback
neutral: The response is factual or neither positive nor negative
mixed: The response contains both positive and negative elements

Confidence Levels#

high: The respondent gave a clear, direct answer
medium: The answer was somewhat indirect or required interpretation
low: The answer was vague or the respondent did not fully address the question

Email Answers#

If you collect an email as a conversation question, it appears in summary.answers like any other answer. Diaform also attempts to extract a valid respondent email into respondent identities during post-processing. New webhook consumers should read extracted emails from respondent.identities or summary.respondent_identities, not from summary.respondent_email.

Next Steps#

To verify that webhook requests are genuinely from Diaform, see Verifying Webhook Signatures.