Slack and Discord webhooks

A site can post its new-sale notifications to one Slack channel and one Discord channel, each through an incoming webhook: a secret URL that lets whoever has it post to that channel.

Create the webhookCopy Anchor Link

PilotFox accepts only each service's documented webhook form, so a URL can never send your sales elsewhere:

Both: https only, that exact host, no port, no user name or password, no #fragment. Anything else is refused with 400 ("Not a Slack incoming webhook URL (https://hooks.slack.com/services/…)" or "Not a Discord webhook URL (https://discord.com/api/webhooks/…)"), and a URL longer than 512 characters with 400 "Invalid request".

Add it in PilotFoxCopy Anchor Link

Open Site settings → Notifications, paste the URL under Slack or Discord, and click Send test to check it. You need the site:update permission (editors and above) and revenue:read on the site, since the channel will receive every sale's amount, source and country.

The URL is stored encrypted and never returned: the settings show only its host and last four characters, such as hooks.slack.com/…a1b2. A webhook can be switched off without deleting it.

Over the API:

# Connect (or replace) the Slack webhook; it is switched on unless you send "enabled": false.
# SLACK_WEBHOOK_URL holds the URL Slack gave you: like the API key, keep it out of the command line itself.
curl -X PUT "https://pilotfox.app/api/v1/sites/SITE_ID/notifications/slack" \
  -H "Authorization: Bearer $PILOTFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"url\": \"$SLACK_WEBHOOK_URL\"}"

# Switch it off, keeping the URL:
curl -X PUT "https://pilotfox.app/api/v1/sites/SITE_ID/notifications/slack" \
  -H "Authorization: Bearer $PILOTFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

# Remove it:
curl -X DELETE "https://pilotfox.app/api/v1/sites/SITE_ID/notifications/slack" \
  -H "Authorization: Bearer $PILOTFOX_API_KEY"

Use /notifications/discord the same way. Each call answers 200 with the site's notification settings:

{
  "data": {
    "recipients": [],
    "members": [{ "userId": "8c314866-bce3-411e-a51b-8e5258b540f5", "name": "Admin", "email": "admin@example.com" }],
    "webhooks": [
      { "kind": "slack", "connected": true, "enabled": true, "urlHint": "hooks.slack.com/…XXXX", "lastError": null, "lastSentAt": null },
      { "kind": "discord", "connected": false, "enabled": false, "urlHint": null, "lastError": null, "lastSentAt": null }
    ]
  }
}

The body takes url, enabled or both. Switching on ("enabled": true) or sending a url needs revenue:read; switching off and deleting need site:update only. Switching a webhook that was never connected is 400 ("Paste a Slack webhook URL first").

Who connected itCopy Anchor Link

PilotFox records who set the webhook's URL, each time it is set: the signed-in member, or the API key used. Before each message, a test included, it checks that this member or key may still see the site's revenue:

• A member must still belong to the organization, not be banned, and have revenue:read on the site.
• An API key must still exist, be enabled and unexpired, hold revenue:read, and not be limited to other sites.

When the check fails, nothing is posted and the webhook shows as failing with the reason, so deleting an API key also stops the webhooks it connected. Switching the webhook off and on again does not change who connected it. To keep it, a member who has revenue:read pastes the URL again (Replace URL): the webhook is then theirs. Webhooks connected before PilotFox recorded this (before the 2026-10-30 update) send nothing until their URL is pasted again.

The message formatCopy Anchor Link

Each message has a bold headline, one line per sale when there are several, and a link to the site's Revenue page.

*3 new sales: $147.00*
• $49.00 · from Hacker News (news.ycombinator.com) · Germany
• $49.00 · from Google (google.com) · France
• $49.00 · from Direct
<https://pilotfox.app/sites/SITE_ID/revenue|Revenue of Docs shop>

A single sale is one line: New sale: $49.00 · from Hacker News (news.ycombinator.com) · Germany. A test message starts with "Test:" and says that no sale was made.

When a delivery failsCopy Anchor Link

Each sale is sent at most once. A delivery is retried once right away after a network error, a 5xx, or a 429 that asks to wait 5 seconds or less; otherwise the message is dropped and the webhook's lastError says why (it clears on the next successful delivery, which sets lastSentAt):

(With "Discord" in place of "Slack" for a Discord webhook.) Redirects are never followed, and the service's own error text is never stored or shown.