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. }

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

При отправке запроса информация считается принятой, если в заголовке 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 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.    _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.             events: [
  14.                "responsible_lead",
  15.                "responsible_contact",
  16.                "responsible_company",
  17.                "responsible_customer",
  18.                "responsible_task"
  19.             ]
  20.          }
  21.       ]
  22.    }
  23. }

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

  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. }