Webhooks

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

Работать с WebHooks через API можно на любом тарифном плане.

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

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

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

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

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

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

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

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

Установка WebHooks

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

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

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

  1. Зайдите в меню Настройки > Интеграции .

  1. В разделе Собственные интеграции нажмите «WEB HOOK».

  1. Введите URL WebHook-а.

  1. Выберите события, при которых будет отправляться уведомление.
  2. Нажмите «Сохранить».

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

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

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

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

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


{
	"leads": {
		"status": {
            "0": {
			    "id": "25399013",
			    "name": "Lead title",
			    "old_status_id": "7039101",
			    "status_id": "142",
			    "price": "0",
			    "responsible_user_id": "123123",
			    "last_modified": "1413554372",
			    "modified_user_id": "123123",
			    "created_user_id": "123123",
			    "date_create": "1413554349",
			    "account_id": "7039099",
			    "custom_fields": [{
					  "id": "427183",
					  "name": "Checkbox custom field",
					  "values": ["1"]
				   },
				  {
					  "id": "427271",
					  "name": "Date custom field",
					  "values": ["1412380800"]
				   },
				  {
					  "id": "1069602",
					  "name": "Checkbox custom field",
					  "values": ["0"]
				   },
				  {
					  "id": "427661",
					  "name": "Text custom field",
				  	  "values": ["Валера"]
				   },
				  {
					  "id": "1075272",
					  "name": "Date custom field",
					  "values": ["1413331200"]
				   }
			   ]
           }
		}
	}
}

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

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


{
	"task": {
		"update": [{
            "0": {
			    "id": "11122233",
			    "element_id": "33322211",
			    "element_type": "2",
			    "task_type": "1",
			    "date_create": "2017-07-20 15:00:00",
			    "text": "Follow-up",
			    "status": "1", // 0 - не завершена, 1 - завершена
			    "account_id": "77711122",
			    "created_user_id": "123123",
			    "last_modified": "2017-07-21 19:00:00",
			    "responsible_user_id": "123123",
			    "complete_till": "2017-07-22 23:59:00",
			    "action_close": "1", // Параметр только для обновления задач. 1 - при текущем обновлении задача была завершена,
			    0 - не была завершена
                "result": { // Результат по задаче приходит, если он был указан.
				    "id": "155155155",
				    "text": "Success"
			    }
             }
		}]
	},
	"account": {
		"subdomain": "test"
	}
}

Примеры массивов неразобранного

Добавление неразобранного:


{
	"unsorted": {
		"add": [{
			"uid": "40789acb990dbb9754dc234e18d2325470612b2284880504d78f258d8f77",
			"category": "forms",
			"account_id": "1312313",
			"user_id": "123123",
			"source": "Заявка с сайта №441310 из формы «Форма #1548921297»",
			"pipeline_id": "142141",
			"source_data": {
				"name_1": {
					"type": "text",
					"id": "name_1",
					"element_type": "1",
					"name": "ФИО",
					"value": "Валерий",
				},
				"23424_1": {
					"type": "multitext",
					"id": "23424_1",
					"element_type": "1",
					"name": "Телефон",
					"value": "23424"
				},
				"form_id": "243222",
				"form_type": "1",
				"date": "156232405",
				"from": "Заявка с сайта №441310 из формы «Форма #1548921297»",
				"origin": {
					"ip": "12.123.123.12",
					"datetime": "Wed Sep 04 2019 19:54:55 GMT+0300 (Москва, стандартное время)",
					"referer": 															"https://test.amocrm.ru/settings/pipeline/leads/1232432",
					"country": "Russian Federation",
					"city": "Moscow",
					"continent_code": "EU",
					"visitor_uid": "202273f9-03cc-42b5-aa4d-71e2ead59ec4"
				}
			},
			"data": {
				"leads": [{
					"date_create": "156232405",
					"visitor_uid": "202273f9-03cc-42b5-aa4d-71e2ead59ec4",
					"created_user_id": "0",
					"modified_user_id": "0",
					"main_user_id": "0",
					"tags": "Заявка с сайта"
				}],
				"contacts":[{
					"name": "contact",
					"custom_fields": [{
						"id": "121507",
						"values": [{
							"enum" : "223111",
							"value" :  "23424"
						}]
					}],
					"date_create": "156232405",
					"visitor_uid": "202273f9-03cc-42b5-aa4d-71e2ead59ec4",
					"created_user_id": "0",
					"modified_user_id": "0",
					"main_user_id": "0",
					"tags": " Заявка с сайта"
				}]
			}
		}]
	},
	"account": {
		"subdomain": "test",
		"id": "1312313",
		"_links": {
			"self": "https://test.amocrm.ru"
		}
	}
}

Обновление неразобранного:


{
	"unsorted": {
		"update": [{
			"uid": "40789acb990dbb9754dc234e18d2325470612b2284880504d78f258d8f77",
			"category": "forms",
			"account_id": "1312313",
			"user_id": "123123",
			"source": "Заявка с сайта №441310 из формы «Форма #1548921297»",
			"pipeline_id": "142141",
			"source_data": {
				"form_id": "243222",
				"form_type": "1",
				"date": "156232405",
				"from": "Заявка с сайта №441310 из формы «Форма #1548921297»",
				"form_name": "Сайт",
				"date": "1567619168",
				"source_uid": "232323",
				"source": "2423424",
				"uid": "24242432",
				"origin": {
					"ip": "12.123.123.12",
					"referer": "https://test.amocrm.ru/settings/pipeline/leads/1541752",
					"visitor_uid": "202273f9-03cc-42b5-aa4d-71e2ead59ec4",
					"datetime": "1567619168"
				}
			},
			"data": {
				"leads": [{
					"id": "24242432",
					"status_id": "424232222",
					"pipeline_id": "4353222",
					"name": "Сделка",
					"created_user_id": "0",
					"date_create": "156760055"
				}],
				"pipeline_id": "4353222",
				"source": "2423424",
				"source_uid": "232323",
				"created_at": "156760055",
			}
		}]
	},
	"account": {
		"subdomain": "test",
		"id": "1312313",
		"_links": {
			"self": "https://test.amocrm.ru"
		}
	}
}

Принятие и отклонение неразобранного считается как их удаление, поэтому при этих действиях будет приходить webhook на удаление неразобранного. Их можно отличить по двум параметрам, в action будет указанно decline если было отклонение или accept если принятие, а так же различается название параметра с id сущностей неразобранного, decline_result и accept_result. Ниже приведены примеры данных webhook.

При отклонении:


{
	"unsorted": {
		"delete": [{
			"action": "decline",
			"uid": "40789acb990dbb9754dc234e18d2325470612b2284880504d78f258d8f77",
			"category": "forms",
			"created_at": "124242341",
			"decline_result": {
				"leads": ["2132111"]
			}
		}]
	},
	"account": {
		"subdomain": "test",
		"id": "1312313",
		"_links": {
			"self": "https://test.amocrm.ru"
		}
	}
}

При принятии:



{
	"unsorted": {
		"delete": [{
			"action": "accept",
			"uid": "40789acb990dbb9754dc234e18d2325470612b2284880504d78f258d8f77",
			"category": "forms",
			"created_at": "124242341",
			"accept_result": {
				"leads": ["2132111"],
				"contacts": ["3454532"]
			}
		}]
	},
	"account": {
		"subdomain": "test",
		"id": "1312313",
		"_links": {
			"self": "https://test.amocrm.ru"
		}
	}
}

Пример массива при входящем сообщении:

{
    "message": {
        "add": {
            [
                "id": "amo12345-31ed-41af-am23-conf1504",
                "chat_id": "2f61amo-c914-r429-m4f1-4005c15o5n0f",
                "author": {
                    "id": "7a389amo2-cr65-46m6-8216-06f39w12q3d8s",
                    "name": "Ivan Ivanov"
                },
                "text": "Hello World!",
                "created_at": "1580116931",
                "origin": "telegram",
                "attachment": {
                    "type": "picture",
                    "link": "https://amojo.amocrm.ru/attachments/db6a2cea-197b-4993-afd3-c0cdfc4cef7b/cc9a7fca-6f5f-4d6f-b39f-6f62ce20d432/amocrm.gif"
                },
                "element_id": "123456789",
                "element_type": "1"
            ]
        }
    }
}

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

Наш сервис ожидает ответ от хука не более 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

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