Webhooks | Docs | Perspective AI

Webhooks push real-time event data to your server whenever something happens in Perspective -- an interview completes, a highlight page is published, or a conversation is flagged. Use them to sync data into your CRM, trigger Slack alerts, or kick off downstream workflows.

Supported Events

Event	Trigger
`conversation.completed`	An interview or concierge session ends.
`highlight.published`	A highlight page is set to public or updated.
`trust.alert`	A conversation is flagged for low trust score or risky content.

Events are delivered as POST requests to the endpoint you configure.

Setting Up a Webhook

Create an HTTPS endpoint on your server that accepts POST requests and returns a 2xx status code.
In Perspective, go to Settings > Automations > Webhooks and add your endpoint URL.
Select the events you want to subscribe to.
Copy the signing secret and store it securely (e.g., as PERSPECTIVE_WEBHOOK_SECRET in your environment).

You can also configure webhooks per-perspective by creating an automation with a webhook channel. This lets you route different events to different endpoints depending on the agent.

Payload Format

Every webhook delivery includes a JSON body with this structure:

{
  "id": "evt_abc123",
  "type": "conversation.completed",
  "created": "2026-03-30T14:22:00Z",
  "data": {
    "conversation_id": "conv_xyz",
    "outline_id": "outline_456",
    "agent_type": "concierge",
    "participant": {
      "email": "alex@example.com"
    },
    "summary_url": "https://getperspective.ai/highlights/abc"
  }
}

The data object varies by event type. For trust.alert, it includes a trust_score field and the reason for flagging. For highlight.published, it includes the highlight page URL and outline metadata.

Custom parameters passed during the interview (via URL params or embed attributes) are included in the data.params object, so you can use them for attribution and routing.

Signature Verification

When configuring a webhook, you can set a custom authorization header (name and value) that Perspective includes with every delivery. Use this to authenticate incoming requests on your server.

Every delivery also includes an X-Idempotency-Key header — a unique identifier for the event. Use it to deduplicate deliveries if your endpoint receives the same event more than once due to retries.

Verify that the authorization header matches your expected value before processing the webhook. Reject any request that does not include a valid header.

Retry Behavior

If your endpoint returns a non-2xx status code or times out, Perspective retries delivery with exponential backoff:

First retry: ~1 minute after the initial attempt
Subsequent retries: exponentially increasing intervals
Maximum retry window: 24 hours

After 24 hours of consecutive failures, the event is dropped. Your endpoint should return 200 as quickly as possible -- offload heavy processing to a background job.

Automation Conditions

Webhooks can be paired with conditions to filter which events get delivered:

Tag filters: Only fire when the conversation has specific tags (tagsAny or tagsAll).
Trust score range: Only fire when the trust score is within a range (trustScoreMin, trustScoreMax).

Configure these in the automation settings alongside your webhook endpoint.

Common Pitfalls & Fixes

Issue: Webhook never fires after interview completes Fix: Check that the automation is enabled and the trigger is set to "per interview." Verify the endpoint URL is reachable from the public internet (localhost will not work).

Issue: Signature verification fails intermittently Fix: Make sure you are verifying against the raw request body, not a parsed-and-re-serialized version. Middleware that modifies the body before your handler runs will break signature checks.

Issue: Duplicate deliveries Fix: Use the id field to deduplicate. Retries reuse the same event ID, so store processed IDs and skip duplicates.