Quickstart: webhook за 5 минут#

Задача — принять первое сообщение от внешнего сервиса в канал PartyFlow. Получится:

• Webhook, привязанный к каналу.
• URL для POST.
• HMAC signing secret (или token-only, если для начала хочется без подписи).
• Первое сообщение, пришедшее curl-запросом.

Для этого гайда вам нужны admin-права в space. Если их нет — попросите админа команды.

Шаг 1. Создать webhook#

В PartyFlow откройте настройки space → Integrations → Incoming webhooks → New webhook.

Заполните:

Нажмите Create. Появится диалог с:

• Webhook URL — скопируйте. Пример: https://api.partyflow.ru/api/v1/webhooks/incoming/whk_1j3k...
• Signing secret — скопируйте, если Require signature = On. Показывается один раз.

Если вы потеряете signing secret, его надо ротировать (старый перестанет работать). URL при этом не меняется.

Шаг 2. Отправить первое сообщение#

Token-only (без подписи)#

WEBHOOK_URL='https://api.partyflow.ru/api/v1/webhooks/incoming/whk_1j3k...'
 
curl -X POST "$WEBHOOK_URL" \
  -H 'Content-Type: application/json' \
  -d '{"text":"Hello from quickstart!"}'

Ожидаемый ответ — HTTP 200. Откройте канал в PartyFlow — сообщение должно появиться в течение секунды.

С подписью (рекомендовано для прода)#

Используем PartyFlow-native схему (похожа на Stripe/Linear):

WEBHOOK_URL='https://api.partyflow.ru/api/v1/webhooks/incoming/whk_1j3k...'
SECRET='whsec_секрет_из_Шага_1'
BODY='{"text":"Hello with signature"}'
 
TS=$(date +%s)
SIG="sha256=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')"
 
curl -X POST "$WEBHOOK_URL" \
  -H 'Content-Type: application/json' \
  -H "X-PartyFlow-Timestamp: $TS" \
  -H "X-PartyFlow-Signature: $SIG" \
  -d "$BODY"

Python-эквивалент — см. guides/verify-signatures.md.

Шаг 3. Попробовать структурированный payload#

Plain text — это скучно. PartyFlow понимает Slack-совместимый формат:

curl -X POST "$WEBHOOK_URL" \
  -H 'Content-Type: application/json' \
  -d '{
    "text": "Deploy finished",
    "attachments": [{
      "color": "good",
      "title": "Release v2.14.0",
      "title_link": "https://github.com/acme/app/releases/tag/v2.14.0",
      "fields": [
        {"title": "Environment", "value": "production", "short": true},
        {"title": "Duration", "value": "4m 12s", "short": true}
      ]
    }]
  }'

В канале появится сообщение с цветной полоской и grid'ом полей. Полный список поддерживаемых полей — reference/message-format.md.

Шаг 4. Триггерить push-уведомления только там, где это критично#

По умолчанию webhook-сообщения не шлют push (чтобы Grafana не разбудила команду ночью скучным deploy'ем). Push срабатывает только при @mention:

{
  "text": "Prod DB down @oncall",
  "severity": "critical",
  "mentions": ["<user-id-oncall-инженера>"]
}

Подробно — concepts/webhooks.md и reference/http-webhook-endpoint.md.

Что дальше#

• concepts/security.md — прежде чем включать webhook в прод, разберитесь с HMAC и ротацией ключей.
• guides/send-grafana-alerts.md — собрать рабочую связку Grafana → PartyFlow.
• reference/http-webhook-endpoint.md — полный справочник по payload и response codes.
• reference/message-format.md — все доступные поля структурированных сообщений.

Частые ошибки#