subscriptions

Подписка — копия ленты уведомлений канала по своему адресу. Очередь и вебхук канала при этом не меняются: основное приложение читает свою ленту, а CRM, аналитика или архив получают ту же ленту отдельно. Каждую доставку Gratio подписывает.

Те же запросы работают по адресу /v1/instances/{idInstance}/subscriptions с заголовком Authorization: Bearer {apiTokenInstance}.

Параметры

Тело POST:

Подписка с таким name уже есть — POST меняет её адрес и секрет, очередь доставки сохраняется. POST без secret выдаёт новый секрет: подпись старым перестаёт сходиться сразу.

Пример запроса

Подписать CRM на ленту канала, секрет создаст Gratio:

curl

curl -X POST "$GRATIO_URL/waInstance$GRATIO_ID/subscriptions/$GRATIO_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "crm",
    "url": "https://crm.example.ru/hooks/gratio"
  }'

Python

import os
import requests

BASE = f"{os.environ['GRATIO_URL']}/waInstance{os.environ['GRATIO_ID']}"
TOKEN = os.environ["GRATIO_TOKEN"]

url = f"{BASE}/subscriptions/{TOKEN}"
payload = {"name": "crm", "url": "https://crm.example.ru/hooks/gratio"}
response = requests.post(url, json=payload, timeout=60)
print(response.status_code, response.json())

Node.js

const { GRATIO_URL, GRATIO_ID, GRATIO_TOKEN } = process.env;
const base = `${GRATIO_URL}/waInstance${GRATIO_ID}`;

const url = `${base}/subscriptions/${GRATIO_TOKEN}`;
const payload = { name: "crm", url: "https://crm.example.ru/hooks/gratio" };
const response = await fetch(url, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(payload),
});
console.log(response.status, await response.json());

PHP

<?php
$base = getenv('GRATIO_URL') . '/waInstance' . getenv('GRATIO_ID');
$url = $base . '/subscriptions/' . getenv('GRATIO_TOKEN');
$payload = ['name' => 'crm', 'url' => 'https://crm.example.ru/hooks/gratio'];

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 60,
]);
$response = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($response);

Пример ответа

Ответ 200 OK:

{
  "id": "sub_9f2c41d07be35a1c86e4f0b2",
  "name": "crm",
  "url": "https://crm.example.ru/hooks/gratio",
  "createdAt": 1791823700,
  "pending": 0,
  "oldestPendingAt": null,
  "dead": 0,
  "lastDeliveredAt": null,
  "lastError": null,
  "lastErrorAt": null,
  "system": false,
  "created": true,
  "secret": "a39e8979effc76a1915fb07c5e3b1d7ada556f9f12974f89312a3486ebe83095"
}

Сохраните secret сразу: Gratio показывает его только в этом ответе.

Поля ответа

Ещё примеры

Список подписок

Все подписки канала с очередью доставки:

curl "$GRATIO_URL/waInstance$GRATIO_ID/subscriptions/$GRATIO_TOKEN"

Ответ 200 OK — подписки по времени создания, со счётчиками доставки:

{
  "subscriptions": [
    {
      "id": "sub_9f2c41d07be35a1c86e4f0b2",
      "name": "crm",
      "url": "https://crm.example.ru/hooks/gratio",
      "createdAt": 1791823700,
      "pending": 2,
      "oldestPendingAt": 1791823905,
      "dead": 0,
      "lastDeliveredAt": 1791823890,
      "lastError": "HTTP 503",
      "lastErrorAt": 1791823906,
      "system": false
    }
  ]
}

Секрет в списке не показывается.

Свой секрет

Секрет задаёте сами — например, чтобы хранить его в своём хранилище секретов заранее:

curl -X POST "$GRATIO_URL/waInstance$GRATIO_ID/subscriptions/$GRATIO_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "crm",
    "url": "https://crm.example.ru/hooks/gratio",
    "secret": "5d0c3f1a9b7e4c2d8a6f0e1b3c5d7e9f"
  }'

В ответе нет поля secret.

Снять подписку

Передайте id подписки в конце пути:

curl -X DELETE "$GRATIO_URL/waInstance$GRATIO_ID/subscriptions/$GRATIO_TOKEN/sub_9f2c41d07be35a1c86e4f0b2"

Ответ 200 OK:

{"removed": true}

Недоставленные уведомления подписки удаляются вместе с ней.

Доставка

Gratio шлёт POST на url. Тело — уведомление целиком (как body в receiveNotification), компактный JSON в UTF-8.

• Уведомления идут по одному, в порядке записи: следующее — после 2xx на текущее. Подписки канала доставляются независимо друг от друга.
• Подписка получает уведомления, записанные после её создания.
• Набор уведомлений — тот же, что у очереди канала: флаги setSettings действуют и на подписки.
• Gratio ждёт ответа до 30 секунд.

Отравленные подписки видно только счётчиком dead в списке: посмотреть и вернуть их пока нельзя. Доставленные, отравленные и истёкшие уведомления подписки хранятся 7 дней.

Повтор отсекайте по X-Gratio-Delivery или по eventId уведомления.

Ошибки

Что дальше

• Проверка подписи — принимать доставку, только если подпись сошлась.
• Вторая система на той же ленте — подписка для CRM по шагам.
• Вебхук — основной приёмник уведомлений.