События продукта через Events API

1. Создайте серверный API-ключ

В разделе «Настройки → API и приватность» создайте ключ с правом events:write. Секрет начинается с snd_live_ и показывается один раз — сохраните его в хранилище секретов вашего сервера. Ключи создают владелец и администраторы после включения двухфакторного входа.

Ключ действует в пределах своих прав и перестаёт работать, если его отозвали или его создатель ушёл из пространства либо потерял право управлять API-ключами.

2. Отправьте событие

POST https://sendalto.com/api/events с заголовком Authorization: Bearer <ключ> и телом в JSON. Неизвестные поля отклоняются.

curl https://sendalto.com/api/events \
  -H "Authorization: Bearer $SENDALTO_EVENTS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "trial_started:user_8f2c1d",
    "name": "trial_started",
    "email": "[email protected]",
    "properties": { "plan": "team", "seats": 5 },
    "occurredAt": "2026-10-06T09:30:00Z"
  }'

// Server-side only (Node.js 18+). The key never reaches a browser.
export async function trackEvent({ externalId, name, email, properties = {}, occurredAt }) {
  const response = await fetch('https://sendalto.com/api/events', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.SENDALTO_EVENTS_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ externalId, name, email, properties, occurredAt }),
  });
  const result = await response.json();
  if (response.ok) return result.data; // { id, duplicate }
  // 429 and 5xx: retry later with the same externalId. Other errors need a fix.
  throw Object.assign(new Error(result.error), { status: response.status, code: result.code });
}

await trackEvent({
  externalId: `trial_started:${user.id}`,
  name: 'trial_started',
  email: user.email,
  properties: { plan: user.plan },
});

3. Ответы, повторы и лимиты

HTTP/1.1 201 Created
{ "data": { "id": "6c7e1d3a-…", "duplicate": false } }

HTTP/1.1 200 OK            (same externalId sent again)
{ "data": { "id": "6c7e1d3a-…", "duplicate": true } }

HTTP/1.1 429 Too Many Requests
{ "error": "Event rate limit reached. Retry after one minute.", "code": "RATE_LIMIT" }

• Защита от дублей. Тот же externalId с тем же названием, адресом и свойствами вернёт 200 с "duplicate": true и ничего не изменит. Тот же externalId для другого события вернёт 409 EVENT_ID_REUSED. Если запрос не дождался ответа или получил 429 либо 5xx, повторите его с тем же externalId.
• Лимит. 600 событий в минуту на пространство; сверх него — 429 RATE_LIMIT. Тело запроса — до 40 КБ.
• Ошибки приходят в JSON с полями error (понятное сообщение) и code — они перечислены ниже.

Что происходит с событием

• Оно сохраняется в пространстве и появляется в списке известных событий в конструкторе сценариев.
• Если есть контакт с таким адресом, для него запускаются активные сценарии с этим событием-триггером (с учётом правила повторного входа каждого сценария), а запуски, для которых это событие — цель, останавливаются.
• Подписки на вебхуки с этим названием события пересылают его на ваш адрес — см. Вебхуки.
• Событие не создаёт контакт и не даёт права писать. Согласие записывается у контактов.