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 an interview finishes and the AI-generated summary is ready.

Example Payload#

{
  "conversation_id": "uuid",
  "agent_id": "uuid",
  "organization_id": "uuid",
  "status": "completed",
  "summary": {
    "respondent_email": "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.",
    "keyword_tags": {
      "positive": ["onboarding", "ease of use"],
      "negative": []
    },
    "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 interview
`organization_id`	string	Your organization ID
`status`	string	Always `"completed"` for this event
`summary`	object or null	AI-generated interview summary
`summary.respondent_email`	string or null	Respondent email extracted from user messages when available
`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 interview sentiment
`summary.urgent_issues`	`string[]`	Critical issues flagged by the AI
`summary.additional_insights`	string	Extra context not covered by questions
`summary.keyword_tags`	object	Categorized keywords extracted from the interview
`summary.keyword_tags.positive`	`string[]`	Positive themes
`summary.keyword_tags.negative`	`string[]`	Negative themes
`summary.actions_called`	array	Automation or tool actions recorded during the interview
`summary.actions_called[].action_type`	string	Type of action
`summary.actions_called[].ended_conversation`	boolean	Whether the action ended the interview
`summary.actions_called[].description`	string	Human-readable action description
`completed_at`	string	ISO 8601 timestamp of when the interview 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 an interview question, it appears in summary.answers like any other answer. Diaform also attempts to extract a valid respondent email into summary.respondent_email during post-processing.

Next Steps#

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