> ## Documentation Index
> Fetch the complete documentation index at: https://docs.politicalcomms.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Real-time webhook notifications for messages, replies, and link clicks. Use cases, payload format, and architecture.

Webhooks deliver real-time notifications when events occur in your account. Common use cases include CRM integration, analytics pipelines, alerting, and triggering automated follow-up campaigns.

## Use cases

<CardGroup cols={2}>
  <Card title="CRM integration" icon="address-card">
    Update contact records when messages are delivered or fail.
  </Card>

  <Card title="Analytics pipelines" icon="chart-line">
    Stream click data to your data warehouse for analysis.
  </Card>

  <Card title="Alerting" icon="bell">
    Notify staff when constituents reply to messages.
  </Card>

  <Card title="Automation" icon="bolt">
    Trigger follow-up campaigns based on engagement.
  </Card>
</CardGroup>

## Five event types

* [`message.sent`](/api-reference/webhooks/events#message-sent) - Message accepted by the carrier.
* [`message.delivered`](/api-reference/webhooks/events#message-delivered) - Carrier confirmed delivery to the recipient's device.
* [`message.failed`](/api-reference/webhooks/events#message-failed) - Carrier rejected the message or delivery failed.
* [`message.replied`](/api-reference/webhooks/events#message-replied) - Inbound SMS/MMS received from a contact.
* [`link.clicked`](/api-reference/webhooks/events#link-clicked) - Recipient clicked a tracking link.

## How webhooks flow

<Steps>
  <Step title="An event occurs">
    A message is sent, delivered, fails, gets a reply, or a tracking link is clicked.
  </Step>

  <Step title="We POST the payload to your endpoint">
    Signed with HMAC-SHA256 over the JSON body, with headers identifying the event type, ID, and timestamp.
  </Step>

  <Step title="Your endpoint validates and acknowledges">
    Validate the signature, persist or queue the event for processing, and return `200` within 10 seconds.
  </Step>

  <Step title="If your endpoint fails, we retry">
    Four total attempts with exponential backoff (immediate, +4s, +16s, +64s). After that, the delivery is marked failed and you can retry manually from the dashboard.
  </Step>
</Steps>

## Where to go next

<CardGroup cols={2}>
  <Card title="Set up an endpoint" icon="plug" href="/api-reference/webhooks/setup">
    Configure event subscriptions, copy your signing secret, and send a test webhook.
  </Card>

  <Card title="Validate signatures" icon="shield-check" href="/api-reference/webhooks/signature-validation">
    HMAC-SHA256 validation pattern with a Node.js example.
  </Card>

  <Card title="Event payload reference" icon="code" href="/api-reference/webhooks/events">
    Full JSON samples for every event type.
  </Card>

  <Card title="Retry policy" icon="rotate-right" href="/api-reference/webhooks/retry-policy">
    Schedule, best practices, and how to make handlers safely idempotent.
  </Card>
</CardGroup>