Skip to main content

​
Goal

Register a webhook endpoint so your backend can react to Sippet activity in near real time.

​
Before you start

  • You need a reachable backend endpoint that can accept webhook requests.
  • Decide which support events matter to downstream systems first.

​
Step 1: create the endpoint

In Settings > Webhooks:
  • add the target URL
  • verify the endpoint belongs to the correct environment
  • keep the first subscription small and observable

​
Step 2: decide what happens downstream

Common webhook consumers include:
  • internal support orchestration services
  • analytics pipelines
  • CRM or ticketing sync jobs
Common event families include:
  • contact.*
  • call.*
  • conversation.*
  • communication.message.*
  • email.classification.*
  • callback.*
  • playbook.run.*

​
Email classification payload

The email classification events use the standard webhook envelope with an email classification record in data. 
type SippetWebhookEnvironment = "live" | "sandbox";
type SippetWebhookPayloadVersion = "2026-05-25";

type EmailClassificationWebhookEventType =
  | "email.classification.created"
  | "email.classification.updated"
  | "email.classification.classified";

type EmailClassificationStatus = "pending" | "classified" | "failed";
type EmailClassificationEffectiveSource = "model" | "manual";

export type EmailClassificationWebhookEvent = {
  id: string;
  type: EmailClassificationWebhookEventType;
  version: SippetWebhookPayloadVersion;
  occurred_at: string;
  organisation_id: string;
  environment: SippetWebhookEnvironment;
  data: {
    id: string;
    communication_message_id: string;
    status: EmailClassificationStatus;
    predicted_label: string | null;
    predicted_confidence: number | null;
    effective_label: string | null;
    effective_source: EmailClassificationEffectiveSource | null;
    provider: string;
    model: string;
    taxonomy_version: string;
    prompt_version: string;
    token_usage: Record<string, unknown> | null;
    estimated_cost: string | null;
    provider_response_id: string | null;
    last_error: string | null;
    classified_at: string | null;
    overridden_at: string | null;
    overridden_by_user_id: string | null;
    inserted_at: string;
    updated_at: string;
  };
};

​
Step 3: monitor delivery history

After enabling the endpoint:
  • review delivery results
  • investigate repeated failures quickly
  • confirm retries do not create duplicate downstream work

​
Example workflow

  • a support event occurs in Sippet
  • your webhook endpoint receives the event
  • your backend stores, routes, or transforms the event for another system

​
What good looks like

  • deliveries succeed consistently
  • your downstream system stays in sync
  • failures are visible and actionable from the console

​
Troubleshooting

  • If deliveries fail, start by checking endpoint availability and response behavior.
  • If your downstream job is too broad, narrow the events you act on first.