API и webhooks CRM: надёжная интеграция

API позволяет внешней системе запросить данные или выполнить разрешённое действие, а webhook уведомляет подписчика о событии. Надёжная интеграция использует оба механизма: событие сообщает об изменении, а API помогает получить актуальное состояние и восстановиться после сбоя.

Контракт и источник истины

Определите владельца каждой сущности, стабильные идентификаторы, обязательные поля, версии схемы и правила удаления. Двусторонняя запись без приоритета создаёт цикл и конфликт. Изменения контракта публикуют совместимо либо через новую версию.

Надёжность доставки

Интеграция должна учитывать:

• Повтор одного запроса или события
• Приход событий не по порядку
• Временную недоступность и повторные попытки
• Ограничения частоты и постраничную загрузку
• Частичный успех пакетной операции
• Сверку и повторную обработку из журнала

Безопасность

Используйте отдельные токены с минимальными правами, ротацию и безопасное хранение. Webhook проверяют по подписи и свежести времени, а секрет не передают в URL. Ответы и журналы не должны раскрывать ключи и лишние персональные данные.

Наблюдаемость

Для каждого обмена нужны correlation ID, время, результат, число попыток и безопасное описание ошибки. Метрики задержки и очереди показывают деградацию до жалобы пользователя. Ручной повтор должен быть идемпотентным.

Спроектируйте интеграцию до первого запроса

Изучите API Taska и обсудите контракт, права и обработку ошибок для вашего сценария.

API для запроса, webhook для события

API позволяет системе получить или изменить данные по контракту, webhook сообщает, что событие произошло. Получатель webhook при необходимости запрашивает актуальное состояние через API. Передача полного объекта удобна, но повышает риск устаревших данных и утечки; состав payload выбирают по задаче и безопасности.

Надёжность доставки

Событие имеет уникальный идентификатор, тип, версию, время и tenant-контекст. Получатель проверяет подпись, быстро подтверждает приём и обрабатывает идемпотентно. Отправитель использует повторные попытки с паузой и dead-letter queue. Порядок событий нельзя считать гарантированным без отдельного механизма версии или последовательности.

Контракт и эксплуатация

Изменение схемы версионируется и имеет период совместимости. Логи скрывают секреты и персональные данные, но сохраняют correlation ID и результат. Метрики показывают задержку, ошибки и повторы. Пилот тестирует дубликат, неверную подпись, таймаут, событие вне порядка и восстановление после недоступности получателя.