WebHooks

WebHooks – это уведомление сторонних приложений посредством отправки уведомлений о событиях, произошедших в amoCRM. Вы можете настроить HTTP адреса ваших приложений и связанные с ними рабочие правила в настройках своего аккаунта в разделе «Интеграции».

Примеры сценариев

  • После успешного завершения сделки вы можете отправить информацию о произошедшей транзакции в ваше приложение для денежного учёта и автоматически сгеренировать счёт для оплаты.
  • Вы можете добавлять e-mail новых контактов в CRM системе в список рассылки (например UniSender).
  • Вы можете настроить смс уведомления о произошедших изменениях в вашем аккаунте.

Список поддерживаемых сущностей

  • Сделка
  • Контакт
  • Компания
  • Покупатель
  • Задача

Список возможных событий

  • Добавление
  • Изменение
  • Удаление
  • Восстановление (сделка, контакт, компания)
  • Смена статуса (сделка)
  • Смена отвественного
  • Добавление примечания (сделка, контакт, компания, покупатель)

Описание параметров в настройках

Имя поля Описание
Имя Устанавливает имя WebHook-а.
URL Устанавливает http адрес стороннего приложения.
Событие Устанавливается список событий, при которых будет отправлен WebHook на указанный URL.

Установка WebHooks

Установка WebHooks включает три следующих шага:

  1. Добавить WebHook
  2. Ассоциировать WebHook с рабочими процессами.
  3. Протестировать интеграцию.

Чтобы создать WebHook

  1. Зайдите в меню Настройки > Интеграции .
  2. В разделе Собственные интеграции нажмите «WEB HOOK».
  3. Введите URL WebHook-а.
  4. Выберите события, при которых будет отправляться уведомление.
  5. Нажмите «Сохранить».

    Для тестирования интеграции

    1. Произведите действие, выбранное при создании WebHook-а.
    2. В вашем приложении проверьте данные, полученные из amoCRM.
    3. Если данные не пришли, проверьте правильность введённого URL и перейдите к пункту 1.

    В каком формате отправляются данные

    WebHook отправляет на стороннее приложение всю информацию о сущности в формате, описанном в GET запросах текущего раздела. POST переменная содержит массив вида {“entity”:{“action”:{массив полей сущности}}} в случае создания и обновления сущности, а также вида {“entity”:{“action”:”id”}} в случае удаления сущности.

    Пример массива

    1. {
    2.     "leads" : {
    3.         "status" : {
    4.             "id" : "25399013" ,
    5.             "name" : "Lead title" ,
    6.             "old_status_id" : "7039101" ,
    7.             "status_id" : "142" ,
    8.             "price" : "0" ,
    9.             "responsible_user_id" : "102525" ,
    10.             "last_modified" : "1413554372" ,
    11.             "modified_user_id" : "102525" ,
    12.             "created_user_id" : "102525" ,
    13.             "date_create" : "1413554349" ,
    14.             "account_id" : "7039099" ,
    15.             "custom_fields" : [
    16.                 {
    17.                     "id" : "427183" ,
    18.                     "name" : "Checkbox custom field" ,
    19.                     "values" : [ "1" ]
    20.                 } ,
    21.                 {
    22.                     "id" : "427271" ,
    23.                     "name" : "Date custom field" ,
    24.                     "values" : [ "1412380800" ]
    25.                 } ,
    26.                 {
    27.                     "id" : "1069602" ,
    28.                     "name" : "Checkbox custom field" ,
    29.                     "values" : [ "0" ]
    30.                 } ,
    31.                 {
    32.                     "id" : "427661" ,
    33.                     "name" : "Text custom field" ,
    34.                     "values" : [ "Валера" ]
    35.                 } ,
    36.                 {
    37.                     "id" : "1075272" ,
    38.                     "name" : "Date custom field" ,
    39.                     "values" : [ "1413331200" ]
    40.                 }
    41.             ]
    42.         }
    43.     }
    44. }

    Пример массива для задач

    Если завершать задачи из раздела задач с результатом, то придет 2 события: закрытие задачи и добавление результата. В случае завершении задачи из карточки, приходит 1 событие о завершении задачи с результатом.

    1. {  
    2.    "task" : {  
    3.       "update" : [  
    4.          {  
    5.             "id" : "11122233" ,
    6.             "element_id" : "33322211" ,
    7.             "element_type" : "2" ,
    8.             "task_type" : "1" ,
    9.             "date_create" : "2017-07-20 15:00:00" ,
    10.             "text" : "Follow-up" ,
    11.             "status" : "1" , // 0 - не завершена, 1 - завершена
    12.             "account_id" : "77711122" ,
    13.             "created_user_id" : "110110" ,
    14.             "last_modified" : "2017-07-21 19:00:00" ,
    15.             "responsible_user_id" : "110110" ,
    16.             "complete_till" : "2017-07-22 23:59:00" ,
    17.             "action_close" : "1" , // Параметр только для обновления задач. 1 - при текущем обновлении задача была завершена,
    18. 0 - не была
    19. завершена
    20.             "result" : {  // Результат по задаче приходит, если он был указан.
    21.                "id" : "155155155" ,
    22.                "text" : "Success"
    23.             }
    24.          }
    25.       ]
    26.    } ,
    27.    "account" : {  
    28.       "subdomain" : "test"
    29.    }
    30. }

    Обработка ответа от хука

    Наш сервис ожидает ответ от хука не более 2 секунд. Если мы не получаем ответ за указанное время или код ответа не успешный (HTTP код не от 100 до 299), мы считаем хук не доставленным, а отклик невалидным.
    Ваш хук может быть отключен при следующем условии:

    • За последние 2 часа было получено более 100 невалидных откликов и последний хук на момент проверки так же является невалидным
    В случае блокировки хук будет отключен в целях безопасности. Вы сможете его активировать повторно в настройках нажав кнопку "Включить", затем сохранить. Также администраторы аккаунта получат уведомление в центр уведомлений об отключении хука.

    Ожидаемый ответ

    При отправке запроса информация считается принятой, если в заголовке http ответа будет возвращён код от 100 до 299, согласно таблице кодов статусов w3.org.

    Первая попытка отправки происходит сразу после совершения выбранного действия. В случае, когда попытка неудачна, произойдёт повторная отправка по правилам, представленным в таблице ниже.

    Номер попытки Время* Коды ответа предыдущей попытки
    2 5 минут 0-99, а также 300 и больше
    3 15 минут 0-99, а также 300 и больше
    4 15 минут 499 или от 500 до 599
    5 1 час 499 или от 500 до 599

    *Время, прошедшее с предыдущей попытки.

    Добавление и удаление WebHooks

    Метод для добавления WebHooks. Ограничение по количеству активных WebHooks - 100.

    URL метода для добавления
    POST /api/v2/webhooks/subscribe
    URL метода для удаления
    POST /api/v2/webhooks/unsubscribe

    Параметры

    Параметр Описание
    url URL, на который необходимо присылать уведомления, должен соответствовать стандарту RFC 2396
    events Список событий, при которых должны отправляться WebHooks

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

    Параметр Описание
    url URL на который необходимо присылать уведомления, должен соответствоать стандарту RFC 2396
    result Удалось ли подписать url на эти события
    _links Массив, содержащий информацию о запросе
    _links/self Массив, содержащий информацию о текущем запросе
    _links/self/href Относительный URL текущего запроса
    _links/self/method Метод текущего запроса
    _embedded Массив, содержащий информацию прилегающую к запросу
    _embedded/items Массив, содержащий информацию по каждому отдельному элементу

    Response Headeres содержит следующие заголовки:

    • Content-Type:application/hal+json
    • Runtime-Timestamp:1508320306

    События

    Название события Описание
    responsible_lead У сделки сменился ответственный
    responsible_contact У контакта сменился ответственный
    responsible_company У компании сменился ответственный
    responsible_customer У покупателя сменился ответственный
    responsible_task У задачи сменился ответственный
    restore_lead Сделка восстановлена из корзины
    restore_contact Контакт восстановлен из корзины
    restore_company Компания восстановлена из корзины
    add_lead Добавлена сделка
    add_contact Добавлен контакт
    add_company Добавлена компания
    add_customer Добавлен покупатель
    add_task Добавлена задача
    update_lead Сделка изменена
    update_contact Контакт изменён
    update_company Компания изменена
    update_customer Покупатель изменен
    update_task Задача изменена
    delete_lead Удалена сделка
    delete_contact Удалён контакт
    delete_company Удалена компания
    delete_customer Удален покупатель
    delete_task Удалена задача
    status_lead У сделки сменился статус
    responsible_lead У сделки сменился ответсвенный
    note_lead Примечание добавлено в сделку
    note_contact Примечание добавлено в контакт
    note_company Примечание добавлено в компанию
    note_customer Примечание добавлено в покупателя

    Пример запроса на добавление

    1. {
    2.    subscribe: [
    3.       {
    4.          url: https: //requestb.in/1hwg3ke1,
    5.          events: [
    6.             "add_lead" ,
    7.             "add_contact" ,
    8.             "add_company" ,
    9.             "add_customer" ,
    10.             "add_task"
    11.          ]
    12.       }
    13.    ]
    14. }

    Пример запроса на удаление

    1. {
    2.    unsubscribe: [
    3.       {
    4.          events: [
    5.             "responsible_lead" ,
    6.             "responsible_contact" ,
    7.             "responsible_company" ,
    8.             "responsible_customer" ,
    9.             "responsible_task"
    10.          ]
    11.       }
    12.    ]
    13. }

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

    1. {
    2.    _links: {
    3.       self: {
    4.          href: "/api/v2/webhooks/subscribe" ,
    5.          method: "post"
    6.       }
    7.    } ,
    8.    _embedded: {
    9.       items: [
    10.          {
    11.             url: https: //requestb.in/1hwg3ke1,
    12.             result: true
    13.          }
    14.       ]
    15.    }
    16. }

    Пример интеграции

    1. $data = array (
    2.    'subscribe' => array (
    3.       array (
    4.          'url' => 'https://requestb.in/1hwg3ke1' ,
    5.          'events' => array (
    6.             "responsible_lead" ,
    7.             "responsible_contact" ,
    8.             "responsible_company" ,
    9.             "responsible_customer" ,
    10.             "responsible_task"
    11.          )
    12.       )
    13.    )
    14. ) ;
    15. $subdomain = 'test' ; #Наш аккаунт - поддомен
    16. #Формируем ссылку для запроса
    17. $link = 'https://' . $subdomain . '.amocrm.ru/api/v2/webhooks/subscribe' ;
    18. /* Нам необходимо инициировать запрос к серверу. Воспользуемся библиотекой cURL (поставляется в составе PHP). Подробнее о
    19. работе с этой
    20. библиотекой Вы можете прочитать в мануале. */
    21. $curl = curl_init ( ) ; #Сохраняем дескриптор сеанса cURL
    22. #Устанавливаем необходимые опции для сеанса cURL
    23. curl_setopt ( $curl ,CURLOPT_RETURNTRANSFER, true ) ;
    24. curl_setopt ( $curl ,CURLOPT_USERAGENT, 'amoCRM-API-client/1.0' ) ;
    25. curl_setopt ( $curl ,CURLOPT_HTTPHEADER, [ 'Accept: application/json' ] ) ;
    26. curl_setopt ( $curl ,CURLOPT_URL, $link ) ;
    27. curl_setopt ( $curl ,CURLOPT_HEADER, false ) ;
    28. curl_setopt ( $curl ,CURLOPT_POSTFIELDS, http_build_query ( $data ) ) ;
    29. curl_setopt ( $curl ,CURLOPT_SSL_VERIFYPEER, 0 ) ;
    30. curl_setopt ( $curl ,CURLOPT_SSL_VERIFYHOST, 0 ) ;
    31. $out = curl_exec ( $curl ) ; #Инициируем запрос к API и сохраняем ответ в переменную
    32. $code = curl_getinfo ( $curl ,CURLINFO_HTTP_CODE) ;
    33. curl_close ( $curl ) ;
    34. /* Теперь мы можем обработать ответ, полученный от сервера. Это пример. Вы можете обработать данные своим способом. */
    35. $code = (int) $code ;
    36. $errors = array (
    37.   301 => 'Moved permanently' ,
    38.   400 => 'Bad request' ,
    39.   401 => 'Unauthorized' ,
    40.   403 => 'Forbidden' ,
    41.   404 => 'Not found' ,
    42.   500 => 'Internal server error' ,
    43.   502 => 'Bad gateway' ,
    44.   503 => 'Service unavailable'
    45. ) ;
    46. try
    47. {
    48.   #Если код ответа не равен 200, 201 или 204 - возвращаем сообщение об ошибке
    49.  if ( ! in_array ( $code , [ 200 , 201 , 204 ] ) )
    50.     throw new Exception( isset ( $errors [ $code ] ) ? $errors [ $code ] : 'Undescribed error' , $code ) ;
    51. }
    52. catch(Exception $E )
    53. {
    54.   die ( 'Ошибка: ' . $E -> getMessage ( ) .PHP_EOL. 'Код ошибки: ' . $E -> getCode ( ) ) ;
    55. }

    Список WebHooks

    Метод для получения списка WebHooks.

    URL метода
    GET /api/v2/webhooks

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

    Параметр Описание
    id Уникальный идентификатор заявки
    url URL на который необходимо присылать уведомления, должен соответствоать стандарту RFC 2396
    events Список событий, при которых должны отправляться WebHooks
    _links Массив, содержащий информацию о запросе
    _links/self Массив, содержащий информацию о текущем запросе
    _links/self/href Относительный URL текущего запроса
    _links/self/method Метод текущего запроса
    _embedded Массив, содержащий информацию прилегающую к запросу
    _embedded/items Массив, содержащий информацию по каждому отдельному элементу

    Response Headers содержит следующие заголовки:

    • Content-Type:application/hal+json
    • Runtime-Timestamp:1508320306

    События

    Название события Описание
    responsible_lead У сделки сменился ответственный
    responsible_contact У контакта сменился ответственный
    responsible_company У компании сменился ответственный
    responsible_customer У покупателя сменился ответственный
    responsible_task У задачи сменился ответственный
    restore_lead Сделка восстановлена из корзины
    restore_contact Контакт восстановлен из корзины
    restore_company Компания восстановлена из корзины
    add_lead Добавлена сделка
    add_contact Добавлен контакт
    add_company Добавлена компания
    add_customer Добавлен покупатель
    add_task Добавлена задача
    update_lead Сделка изменена
    update_contact Контакт изменён
    update_company Компания изменена
    update_customer Покупатель изменен
    update_task Задача изменена
    delete_lead Удалена сделка
    delete_contact Удалён контакт
    delete_company Удалена компания
    delete_customer Удален покупатель
    delete_task Удалена задача
    status_lead У сделки сменился статус
    responsible_lead У сделки сменился ответсвенный
    note_lead Примечание добавлено в сделку
    note_contact Примечание добавлено в контакт
    note_company Примечание добавлено в компанию
    note_customer Примечание добавлено в покупателя

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

    1. {
    2.    _links: {
    3.       self: {
    4.          href: "/api/v2/webhooks" ,
    5.          method: "get"
    6.       }
    7.    } ,
    8.    _embedded: {
    9.       items: [
    10.          {
    11.             id: 5881 ,
    12.             url: https: //requestb.in/1hwg3ke1,
    13.             disabled: false ,
    14.             events: [
    15.                "responsible_lead" ,
    16.                "responsible_contact" ,
    17.                "responsible_company" ,
    18.                "responsible_customer" ,
    19.                "responsible_task"
    20.             ]
    21.          }
    22.       ]
    23.    }
    24. }

    Пример интеграции

    1. $subdomain = 'test' ; #Наш аккаунт - поддомен
    2. #Формируем ссылку для запроса
    3. $link = 'https://' . $subdomain . '.amocrm.ru/private/api/v2/webhooks' ;
    4. Нам необходимо инициировать запрос к серверу. Воспользуемся библиотекой cURL (поставляется в составе PHP) . Подробнее о
    5. работе с этой
    6. библиотекой Вы можете прочитать в мануале .
    7.  
    8. $curl = curl_init ( ) ; #Сохраняем дескриптор сеанса cURL
    9. #Устанавливаем необходимые опции для сеанса cURL
    10. curl_setopt ( $curl ,CURLOPT_RETURNTRANSFER, true ) ;
    11. curl_setopt ( $curl ,CURLOPT_USERAGENT, 'amoCRM-API-client/1.0' ) ;
    12. curl_setopt ( $curl ,CURLOPT_HTTPHEADER, [ 'Accept: application/json' ] ) ;
    13. curl_setopt ( $curl ,CURLOPT_URL, $link ) ;
    14. curl_setopt ( $curl ,CURLOPT_HEADER, false ) ;
    15. curl_setopt ( $curl ,CURLOPT_SSL_VERIFYPEER, 0 ) ;
    16. curl_setopt ( $curl ,CURLOPT_SSL_VERIFYHOST, 0 ) ;
    17.  
    18. $out = curl_exec ( $curl ) ; #Инициируем запрос к API и сохраняем ответ в переменную
    19. $code = curl_getinfo ( $curl ,CURLINFO_HTTP_CODE) ;
    20. curl_close ( $curl ) ;
    21. Теперь мы можем обработать ответ, полученный от сервера. Это пример. Вы можете обработать данные своим способом.
    22.  
    23. $code = (int) $code ;
    24. $errors = array (
    25.   301 => 'Moved permanently' ,
    26.   400 => 'Bad request' ,
    27.   401 => 'Unauthorized' ,
    28.   403 => 'Forbidden' ,
    29.   404 => 'Not found' ,
    30.   500 => 'Internal server error' ,
    31.   502 => 'Bad gateway' ,
    32.   503 => 'Service unavailable'
    33. ) ;
    34. try
    35. {
    36.   #Если код ответа не равен 200 или 204 - возвращаем сообщение об ошибке
    37.  if ( $code != 200 && $code != 204 )
    38.     throw new Exception( isset ( $errors [ $code ] ) ? $errors [ $code ] : 'Undescribed error' , $code ) ;
    39. }
    40. catch(Exception $E )
    41. {
    42.   die ( 'Ошибка: ' . $E -> getMessage ( ) .PHP_EOL. 'Код ошибки: ' . $E -> getCode ( ) ) ;
    43. }