# Discord

The Discord integration sends real-time subscription notifications to your Discord channels via webhooks. Get instant visibility into subscription activity with beautifully formatted, color-coded embed messages that make it easy to monitor revenue, track trials, and respond to billing issues as they happen.

In the **Communication** section within **Integrations**, you can connect your Discord account to Superwall:

<img src="__img0" />

Features [#features]

* **Rich Embed Messages**: Beautiful, color-coded notifications with emoji indicators for quick visual parsing
* **Event Type Filtering**: Choose between revenue-only events or all subscription lifecycle events
* **Real-Time Notifications**: Instant alerts when subscription events occur
* **Smart Formatting**: Currency formatting, country names, and human-readable descriptions
* **Flexible Revenue Reporting**: Report either gross revenue or net proceeds after store fees
* **Anonymous User Handling**: Configurable behavior for users without an identified app user ID
* **Custom Event Names**: Override default event titles to match your team's terminology
* **Sandbox Indicators**: Clear visual badge when events come from test environments

Configuration [#configuration]

Required Settings [#required-settings]

| Field             | Description                                     | Example                                         |
| ----------------- | ----------------------------------------------- | ----------------------------------------------- |
| `integration_id`  | Must be set to `"discord"`                      | `"discord"`                                     |
| `webhook_url`     | Discord webhook URL from your server            | `"https://discord.com/api/webhooks/123/abc..."` |
| `sales_reporting` | Whether to report gross Revenue or net Proceeds | `"Revenue"` or `"Proceeds"`                     |

Optional Settings [#optional-settings]

| Field                     | Description                                            | Default                     |
| ------------------------- | ------------------------------------------------------ | --------------------------- |
| `event_type`              | Filter which events to send                            | `"All Subscription Events"` |
| `anonymous_user_behavior` | How to handle events from users without an app user ID | `"send"`                    |
| `eventNameMappings`       | Custom mapping to rename default event titles          | None                        |

Example Configuration [#example-configuration]

```json
{
  "integration_id": "discord",
  "webhook_url": "https://discord.com/api/webhooks/1234567890/abcdefghijklmnop",
  "sales_reporting": "Revenue",
  "event_type": "All Subscription Events",
  "anonymous_user_behavior": "send",
  "eventNameMappings": {
    "sw_subscription_start": "New Premium Member!",
    "sw_trial_start": "New Trial Started"
  }
}
```

Creating a Discord Webhook [#creating-a-discord-webhook]

1. Open your Discord server
2. Go to **Server Settings** (click the server name → Settings)
3. Navigate to **Integrations** → **Webhooks**
4. Click **New Webhook**
5. Configure the webhook:
   * **Name**: Choose a name (e.g., "Superwall Events")
   * **Channel**: Select the channel where notifications will appear
   * **Avatar**: Optionally customize the webhook's avatar
6. Click **Copy Webhook URL**
7. Paste the URL into your integration configuration

**Tip**: Create a dedicated channel like `#subscription-events` or `#revenue-alerts` to keep notifications organized.

Event Filtering [#event-filtering]

The `event_type` setting controls which events are sent to Discord:

All Subscription Events (Default) [#all-subscription-events-default]

Sends every subscription lifecycle event:

* Trial starts and conversions
* New subscriptions
* Renewals
* Cancellations and expirations
* Billing issues
* Product changes
* Refunds

**Best for**: Teams that want complete visibility into all subscription activity.

Revenue Events Only [#revenue-events-only]

Only sends events with non-zero revenue:

* New paid subscriptions
* Renewals
* Trial conversions
* One-time purchases
* Refunds (negative revenue)

**Skips**: Trial starts, cancellations, expirations, billing issues (unless they have revenue attached).

**Best for**: Teams focused on revenue notifications without the noise of non-revenue events.

Message Format [#message-format]

Discord messages are sent as rich embeds with the following structure:

Embed Structure [#embed-structure]

```
┌─────────────────────────────────────────┐
│ [Superwall Logo] Superwall              │  ← Author
├─────────────────────────────────────────┤
│ 💰 New Subscriber                       │  ← Title (with emoji)
│                                         │
│ $9.99 subscription started from         │  ← Description
│ United States                           │
├─────────────────────────────────────────┤
│ 👤 User      🎯 Product    📱 Store     │  ← Fields (inline)
│ user_123    com.app.pro   App Store •   │
│                           United States │
│                                         │
│ 💰 Revenue                              │  ← Revenue field
│ $9.99                                   │
├─────────────────────────────────────────┤
│ Powered by Superwall    Jan 15, 2024    │  ← Footer + Timestamp
└─────────────────────────────────────────┘
```

Embed Fields [#embed-fields]

| Field                    | Description                | When Shown              |
| ------------------------ | -------------------------- | ----------------------- |
| 👤 User                  | User ID or "Anonymous"     | Always                  |
| 🎯 Product               | Product identifier         | Always                  |
| 📱 Store                 | Store name and country     | Always                  |
| 💰 Revenue / 💵 Proceeds | Formatted amount           | When price ≠ 0          |
| ⚙️ Sandbox               | Test environment indicator | Sandbox events only     |
| 🎁 Offer                 | Promotional offer code     | When offer code present |
| 🔄 Product Change        | Old → New product          | Product change events   |

Event Titles and Colors [#event-titles-and-colors]

Each event type has a distinct emoji, title, and color for quick visual identification.

Color Coding [#color-coding]

| Color  | Hex Code  | Meaning                                               |
| ------ | --------- | ----------------------------------------------------- |
| Green  | `#36A64F` | Revenue events (purchases, renewals, conversions)     |
| Blue   | `#3498DB` | Trial events (non-revenue)                            |
| Red    | `#FA6A6A` | Negative events (cancellations, refunds, expirations) |
| Orange | `#FF9500` | Billing issues                                        |
| Purple | `#9B59B6` | Product changes                                       |
| Gray   | `#666666` | Other events                                          |

Event Title Reference [#event-title-reference]

Trial Events [#trial-events]

| Event             | Title                | Color |
| ----------------- | -------------------- | ----- |
| Trial Start       | 🤩 Trial Start       | Blue  |
| Trial Conversion  | 💰 Trial Conversion  | Green |
| Trial Cancelled   | 😞 Cancelled Trial   | Red   |
| Trial Refunded    | 🤬 Refunded Trial    | Red   |
| Trial Expired     | 😞 Expired Trial     | Red   |
| Trial Uncancelled | 🤩 Trial Uncancelled | Blue  |

Intro Offer Events [#intro-offer-events]

| Event              | Title                     | Color |
| ------------------ | ------------------------- | ----- |
| Intro Start (free) | 🤩 Intro Offer Start      | Blue  |
| Intro Start (paid) | 💰 Intro Offer Start      | Green |
| Intro Conversion   | 💰 Intro Offer Conversion | Green |
| Intro Cancelled    | 😞 Cancelled Intro Offer  | Red   |
| Intro Refunded     | 🤬 Refunded Intro Offer   | Red   |

Subscription Events [#subscription-events]

| Event            | Title                       | Color |
| ---------------- | --------------------------- | ----- |
| New Subscription | 💰 New Subscriber           | Green |
| Renewal          | 💰 Renewal                  | Green |
| Cancellation     | 😞 Cancelled Subscription   | Red   |
| Refund           | 🤬 Refunded Subscription    | Red   |
| Expiration       | 😞 Expired Subscription     | Red   |
| Uncancellation   | 🤩 Subscription Uncancelled | Green |

Other Events [#other-events]

| Event               | Title                  | Color  |
| ------------------- | ---------------------- | ------ |
| One-Time Purchase   | 💰 One-Time Purchase   | Green  |
| Product Change      | 😵‍💫 Product Change   | Purple |
| Billing Issue       | 🫠 Billing Issue       | Orange |
| Subscription Paused | ⏸️ Subscription Paused | Gray   |

Revenue Display [#revenue-display]

Revenue vs Proceeds [#revenue-vs-proceeds]

The `sales_reporting` setting controls which amount is displayed:

* **Revenue**: The full price charged to the customer (e.g., $9.99)
* **Proceeds**: The amount after store fees (e.g., $8.49 after Apple's 15-30% commission)

The field label changes based on your setting:

* Revenue mode: "💰 Revenue"
* Proceeds mode: "💵 Proceeds"

Currency Formatting [#currency-formatting]

Amounts are automatically formatted with the correct currency symbol and locale:

* `$9.99` for USD
* `€9.99` for EUR
* `£9.99` for GBP
* `¥999` for JPY

Zero-Value Events [#zero-value-events]

Events without revenue (trial starts, cancellations, expirations) do not show a revenue field, keeping the message compact.

Refunds [#refunds]

Refunds display negative amounts:

* "💰 Revenue: -$9.99"

Anonymous User Handling [#anonymous-user-handling]

The `anonymous_user_behavior` setting controls how events from unidentified users are handled:

Send (Default) [#send-default]

* Events from anonymous users are sent to Discord
* User field displays "Anonymous"
* Useful for complete visibility into all subscription activity

Don't Send [#dont-send]

* Events from anonymous users are skipped
* No notification is sent to Discord
* Useful if you only want to track identified users

Sandbox Events [#sandbox-events]

Events from sandbox/test environments are clearly marked:

* A "⚙️ Sandbox" field is added with value "Test Environment"
* Helps distinguish test events from production activity
* Production events do not show any environment indicator

Custom Event Names [#custom-event-names]

Use `eventNameMappings` to customize event titles:

```json
{
  "eventNameMappings": {
    "sw_trial_start": "🎉 New Trial User!",
    "sw_subscription_start": "💎 VIP Member Joined",
    "sw_renewal": "🔄 Subscription Renewed",
    "sw_subscription_cancelled": "👋 Member Churned"
  }
}
```

Available Event Keys [#available-event-keys]

| Key                         | Default Title             |
| --------------------------- | ------------------------- |
| `sw_trial_start`            | 🤩 Trial Start            |
| `sw_trial_converted`        | 💰 Trial Conversion       |
| `sw_trial_cancelled`        | 😞 Cancelled Trial        |
| `sw_subscription_start`     | 💰 New Subscriber         |
| `sw_renewal`                | 💰 Renewal                |
| `sw_subscription_cancelled` | 😞 Cancelled Subscription |
| `sw_subscription_expired`   | 😞 Expired Subscription   |
| `sw_refund`                 | 🤬 Refunded Subscription  |
| `sw_billing_issue`          | 🫠 Billing Issue          |
| `sw_product_change`         | 😵‍💫 Product Change      |
| `sw_non_renewing_purchase`  | 💰 One-Time Purchase      |

Testing the Integration [#testing-the-integration]

1\. Validate Credentials [#1-validate-credentials]

The integration validates your webhook URL by sending a test event. If the URL is invalid or the webhook has been deleted, validation will fail.

2\. Send a Test Event [#2-send-a-test-event]

Trigger a subscription event from your app (or use sandbox mode) to verify messages appear correctly.

3\. Verify in Discord [#3-verify-in-discord]

Check your configured channel for the notification:

* Confirm the embed appears with correct formatting
* Verify colors match the event type
* Check that fields display correct information

4\. Test Scenarios [#4-test-scenarios]

* [ ] New subscription shows green with 💰 emoji
* [ ] Trial start shows blue with 🤩 emoji
* [ ] Cancellation shows red with 😞 emoji
* [ ] Revenue field shows correct amount
* [ ] Sandbox events show "⚙️ Sandbox" field
* [ ] Revenue-only filter skips zero-price events
* [ ] Anonymous users show "Anonymous" or are skipped per setting
* [ ] Custom event names appear in title

Best Practices [#best-practices]

1. **Create a dedicated channel**: Keep subscription notifications separate from general chat to avoid noise and make monitoring easier.

2. **Use Revenue Events Only for busy apps**: If you have high volume, filtering to revenue-only events reduces noise while keeping you informed of important transactions.

3. **Set up channel notifications**: Configure Discord channel notification settings (e.g., only notify for @mentions) to avoid constant pings.

4. **Consider multiple webhooks**: Create separate webhooks for different event types (e.g., one for revenue in `#sales`, one for all events in `#subscription-logs`).

5. **Monitor billing issues**: Pay special attention to orange "🫠 Billing Issue" notifications—these represent potential revenue at risk.

6. **Use meaningful custom names**: If you customize event names, make them clear and actionable for your team.

Common Use Cases [#common-use-cases]

Sales Celebration Channel [#sales-celebration-channel]

Create a `#sales` channel with revenue-only events:

```json
{
  "event_type": "Revenue Events Only",
  "sales_reporting": "Revenue"
}
```

Celebrate new subscribers and renewals with your team!

Churn Monitoring [#churn-monitoring]

Create a `#churn-alerts` channel and filter to cancellation events using a separate integration instance:

* Monitor cancellation patterns
* Quickly identify if something is causing unusual churn
* React to billing issues before they become cancellations

Customer Success Integration [#customer-success-integration]

Use the user ID field to quickly look up users in your CRM or support system:

* Click the dashboard URL in the embed to view user details
* Reach out proactively to users who cancelled
* Thank high-value subscribers personally

Team Revenue Dashboard [#team-revenue-dashboard]

Display the Discord channel on a team dashboard or TV:

* Real-time visualization of subscription activity
* Color-coded events make it easy to gauge health at a glance
* Celebrate wins and identify issues quickly

Troubleshooting [#troubleshooting]

Messages Not Appearing [#messages-not-appearing]

**Possible causes:**

* Invalid webhook URL
* Webhook was deleted in Discord
* Channel permissions prevent webhook posting
* Event filtered out by `event_type` setting

**Solutions:**

1. Verify the webhook still exists in Server Settings → Integrations
2. Check that the webhook has permission to post in the target channel
3. Confirm `event_type` setting includes the event you're expecting
4. Re-create the webhook if it was deleted

Webhook Rate Limited [#webhook-rate-limited]

**Possible causes:**

* Discord rate limits webhook requests (30 requests per minute per channel)
* High volume of subscription events

**Solutions:**

1. Use "Revenue Events Only" to reduce volume
2. Consider using a less busy channel
3. Events will be queued and retried automatically

Wrong Event Names or Emojis [#wrong-event-names-or-emojis]

**Possible causes:**

* Custom `eventNameMappings` overriding defaults
* Unexpected event type mapping

**Solutions:**

1. Review your `eventNameMappings` configuration
2. Check the event title reference table above
3. Remove custom mappings to restore defaults

Missing Revenue Field [#missing-revenue-field]

**Possible causes:**

* Event has zero price (normal for trial starts, cancellations)
* This is expected behavior

**Solutions:**

* Revenue field only appears when price ≠ 0
* Trial starts, cancellations, and expirations typically have no revenue

Sandbox Badge Appearing [#sandbox-badge-appearing]

**Possible causes:**

* Event came from sandbox/test environment
* This is expected behavior

**Solutions:**

* The "⚙️ Sandbox" field only appears for sandbox events
* Verify you're testing in the correct environment

Rate Limits [#rate-limits]

Discord enforces rate limits on webhooks:

| Limit                 | Value                        |
| --------------------- | ---------------------------- |
| Requests per minute   | 30 per channel               |
| Embed limit           | 10 embeds per message        |
| Total character limit | 6,000 characters per message |

The integration sends one embed per event, which is well within these limits. For extremely high-volume applications, consider using the "Revenue Events Only" filter.

API Reference [#api-reference]

Endpoint [#endpoint]

Events are sent directly to your Discord webhook URL:

```
POST https://discord.com/api/webhooks/{webhook_id}/{webhook_token}
```

Request Headers [#request-headers]

```
Content-Type: application/json
```

Request Body [#request-body]

```json
{
  "embeds": [
    {
      "author": {
        "name": "Superwall",
        "icon_url": "https://superwall.com/favicon.ico"
      },
      "title": "💰 New Subscriber",
      "description": "$9.99 subscription started from United States",
      "url": "https://superwall.com/applications/{app_id}",
      "color": 3582031,
      "thumbnail": {
        "url": "https://superwall.com/favicon.ico"
      },
      "fields": [
        { "name": "👤 User", "value": "user_123", "inline": true },
        { "name": "🎯 Product", "value": "com.app.premium", "inline": true },
        { "name": "📱 Store", "value": "App Store • United States", "inline": true },
        { "name": "💰 Revenue", "value": "$9.99", "inline": true }
      ],
      "timestamp": "2024-01-15T10:30:00.000Z",
      "footer": {
        "text": "Powered by Superwall",
        "icon_url": "https://superwall.com/favicon.ico"
      }
    }
  ]
}
```

Response [#response]

**Success**: `204 No Content` (Discord returns no body on success)

**Error**:

* `400 Bad Request`: Invalid embed structure
* `401 Unauthorized`: Invalid webhook token
* `404 Not Found`: Webhook was deleted
* `429 Too Many Requests`: Rate limited