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

# Webhooks & Push Notifications Integrations

> Configure webhooks, push notifications, and delivery infrastructure for real-time engagement.

<Info>
  Configure webhooks and push notification infrastructure to stream real-time events and engage users reliably.
</Info>

<CardGroup cols={3}>
  <Card title="Webhooks" icon="plug">Deliver real-time events to your backend</Card>
  <Card title="Certificates" icon="file-certificate">Upload APNs / FCM / Baidu credentials</Card>
  <Card title="Chat Events" icon="comments">Channel & conversation notifications</Card>
  <Card title="Community Events" icon="users">Post, comment, story & event notifications</Card>
  <Card title="Live Stream Events" icon="video">Standalone live stream notifications</Card>
  <Card title="Custom Payloads" icon="code">Tailor notification content per event</Card>
</CardGroup>

## Webhooks

<Info>Need full event catalog, payload schema, retry logic, and signature details? See the complete reference: <a href="/analytics-and-moderation/social+-apis-and-services/webhook-event">Webhook Events Reference</a>.</Info>

<Steps>
  <Step title="Add Endpoint">Enter HTTPS URL in **Settings → Webhook** section.</Step>
  <Step title="Secret Issued">Console generates secret key tied to that URL.</Step>
  <Step title="Validate Signature">Configure backend to verify HMAC (secret) per event.</Step>
  <Step title="Rotate Secret">Delete & re-add endpoint if compromise suspected.</Step>
</Steps>

<Warning>Use publicly reachable HTTPS endpoints; avoid including query secrets in the URL.</Warning>

<AccordionGroup>
  <Accordion title="Best Practices">Idempotent processing, 200 fast ACK then async work, exponential retry logic on your side.</Accordion>
  <Accordion title="Security">Restrict IPs if possible; verify signature before queuing work.</Accordion>
  <Accordion title="Versioning">Include event schema version in payload to future‑proof consumers.</Accordion>
</AccordionGroup>

## Push Notifications

Navigate to **Settings → Push notifications** in the console to manage notification settings and certificates.

<img src="https://mintcdn.com/social-b97141fb/g7VmEe9XMeck-8PT/images/console-push-notifications-overview.png?fit=max&auto=format&n=g7VmEe9XMeck-8PT&q=85&s=42c3e7433f72cade447f91f2cdcf4624" alt="Push notifications overview" width="1280" height="900" data-path="images/console-push-notifications-overview.png" />

### Enable Push Notifications

Use the master toggle at the top of the page to enable or disable push notifications for the entire network.

<Warning>Turning the master toggle OFF immediately disables **all** push events (Chat, Community, Live Stream). Certificates must be uploaded and active before toggling events, or notifications will silently fail.</Warning>

### Certificates

Multiple certificates can be stored per platform (e.g., staging + production), but only **one can be active at a time** per platform/provider.

<Warning>Starting June 01, 2024, Google will no longer support mobile push notifications via legacy FCM v1 APIs. Migrate to FCM v1 before this date.</Warning>

| Field                      | Platform Scope | Purpose                                           |
| -------------------------- | -------------- | ------------------------------------------------- |
| Certificate Name           | All            | Internal tracking label                           |
| Platform                   | iOS / Android  | Target OS                                         |
| Provider (Android)         | Android        | Firebase Cloud Messaging (FCM) / Baidu Cloud Push |
| Service Account JSON (FCM) | Android        | FCM v1 service account credentials                |
| .p12 / .p8 Upload          | iOS            | APNs authentication material                      |
| Credential Password        | iOS            | Password for .p12 if set                          |

<Steps>
  <Step title="Prepare Credential">Obtain APNs .p12/.p8 certificate or FCM service account JSON / Baidu server keys.</Step>
  <Step title="Upload">Console → **Settings → Push notifications → Certificates → Add new certificate**.</Step>
  <Step title="Activate">Toggle the **Active** switch for the certificate you want to use per environment.</Step>
  <Step title="Verify">Send a test notification to confirm delivery.</Step>
</Steps>

<Info>Keep staging & production certificates clearly labeled to avoid cross‑environment delivery errors.</Info>

### Notification Events

Configure which events trigger push notifications. Events are organized into three tabs:

<img src="https://mintcdn.com/social-b97141fb/g7VmEe9XMeck-8PT/images/console-push-notifications-chat-events.png?fit=max&auto=format&n=g7VmEe9XMeck-8PT&q=85&s=47a71e0b8d4fdf3a5659033db2f51264" alt="Chat events configuration" width="1280" height="900" data-path="images/console-push-notifications-chat-events.png" />

<Tabs>
  <Tab title="Chat Events">
    Chat-related push notification events:

    | Event                                                 | Description                                  |
    | ----------------------------------------------------- | -------------------------------------------- |
    | When a new channel is created                         | Notifies users when a new channel is created |
    | When a user joins a channel                           | Notifies when a user joins a channel         |
    | When a user joins a conversation                      | Notifies when a user joins a conversation    |
    | When there is a new message in the users channel      | Notifies on new messages in channels         |
    | When there is a new message in the users conversation | Notifies on new messages in conversations    |

    Each event has an **Allow** toggle and an **Actions** button to customize the notification message.
  </Tab>

  <Tab title="Community Events">
    Community events are grouped into subcategories:

    **Post-related events**

    | Event                                              | Description                      |
    | -------------------------------------------------- | -------------------------------- |
    | When someone creates a new post in the community   | New post notification            |
    | When someone react to your posts                   | Reaction notification            |
    | When your post has been approved                   | Moderation approval notification |
    | When there is a post that requires review from you | Moderator review request         |

    **Comment-related events**

    | Event                                 | Description                   |
    | ------------------------------------- | ----------------------------- |
    | When someone comments on your posts   | Comment notification          |
    | When someone replies to your comments | Reply notification            |
    | When someone reacts to your comments  | Comment reaction notification |
    | When someone comments on your story   | Story comment notification    |

    **Story-related events**

    | Event                                             | Description                 |
    | ------------------------------------------------- | --------------------------- |
    | When someone creates a new story in the community | New story notification      |
    | When someone reacts to your story                 | Story reaction notification |

    **Live stream-related events**

    | Event                                              | Description                        |
    | -------------------------------------------------- | ---------------------------------- |
    | When someone starts a live stream in the community | Community live stream notification |

    **Event-related events**

    | Event                                                  | Description                |
    | ------------------------------------------------------ | -------------------------- |
    | When an event user marked as 'Going' is about to start | Upcoming event reminder    |
    | When an event user marked as 'Going' has started       | Event started notification |
  </Tab>

  <Tab title="Live Stream Events">
    Standalone live stream push notification events:

    | Event                                        | Description                                           |
    | -------------------------------------------- | ----------------------------------------------------- |
    | When someone starts a standalone live stream | Notifies followers about a new standalone live stream |

    <Info>This tab covers standalone live streams only. Community live stream notifications are configured under the **Community Events** tab.</Info>
  </Tab>
</Tabs>

### Custom Push Message

Click the **Actions** (pencil icon) button next to any event to customize the notification message template. Keep messages concise (\<140 chars) and actionable.

<AccordionGroup>
  <Accordion title="Localization">Store translation keys instead of raw strings; expand at client side.</Accordion>
  <Accordion title="Personalization">Include displayName when appropriate but avoid sensitive content in payload.</Accordion>
  <Accordion title="Rate Limiting">Throttle bursts to prevent notification fatigue.</Accordion>
</AccordionGroup>

## Monitoring & Metrics

| Metric               | Description                          | Trigger                                       |
| -------------------- | ------------------------------------ | --------------------------------------------- |
| Delivery Success %   | Successful pushes / total            | Drop \< 95% → inspect certs & provider status |
| Cert Days to Expiry  | Soonest certificate expiry           | \< 30 days → schedule renewal                 |
| Event Coverage       | Enabled events / intended events     | Gap → enable missing categories               |
| Webhook Failure Rate | 4xx/5xx responses / total deliveries | > 2% → investigate endpoint health            |

## Troubleshooting

| Issue                   | Likely Cause                | Fix                                         |
| ----------------------- | --------------------------- | ------------------------------------------- |
| No push delivered       | Inactive certificate        | Activate correct cert in Certificates table |
| Some events silent      | Event toggle off            | Enable event under the appropriate tab      |
| FCM legacy errors       | Using deprecated FCM v1 API | Migrate to FCM v1 with service account JSON |
| Webhook 401 errors      | Secret mismatch             | Regenerate secret and update backend        |
| Elevated retries        | Endpoint latency            | Optimize processing / return 200 quickly    |
| Duplicate notifications | Missing idempotency         | Track delivery IDs, discard repeats         |

## Quick Reference

<CardGroup cols={2}>
  <Card title="Master Toggle" icon="power-off">Enables all downstream push events</Card>
  <Card title="Active Cert" icon="certificate">One active per platform/provider</Card>
  <Card title="Rotate Window" icon="calendar">Renew ≥30 days before expiry</Card>
  <Card title="Webhook Security" icon="shield">Verify signature HMAC</Card>
</CardGroup>

## Related

<CardGroup cols={2}>
  <Card title="Security" icon="lock" href="./security">Secure Mode & mTLS</Card>
  <Card title="Branding" icon="image" href="./branding">Console visuals & brand account</Card>
</CardGroup>