WebHooks
WebHooks is the notification of third-party applications by sending notifications of events that occurred in amoCRM. You can configure the HTTP addresses of your applications and associated work rules in your account settings in the “Integrations” section.
Sample scenarios
- After the successful completion of the lead, you can send information about the lead that has occurred in your application for financial accounting and automatically aggregate the account for payment.
- You can add e-mail of new contacts in the CRM system to the mailing list (for example, UniSender).
- You can set up SMS notifications about changes in your account.
List of supported entities
- Lead
- Contact
- Company
- Customer
- Task
List of possible events
- Adding
- Changing
- Deleting
- Restoring (lead, contact, company)
- Changing the status (lead)
- Changing the responsible user
- Adding a note (lead, contact, company, customer)
Description of the parameters in the settings
Field name | Description |
---|---|
Name | Sets the name of the WebHook |
URL | Sets the http address of a third-party application |
Event | Set the list of events for which WebHook will be sent to the specified URL. |
Setting up WebHooks
The installation of WebHooks includes the following three steps:
- Adding WebHook
- Associating the WebHook with the workflows.
- Test integration.
To create a WebHook:
- Go to Settings > Integration.
- In the Your Integrations section, click “Webhooks”.
- Enter the WebHook URL.
- Select the trigger when the notification will be sent.
- Click “Save”.
To test the integration
- Perform the action selected when creating the WebHook.
- In your application, check the data from amoCRM.
- If the data does not arrive, check that the URL you entered is correct and go to step 1
In what format is the data sent
The WebHook sends all the information about the entity in the format described in the GET requests of the current section to the third-party application. The POST variable contains an array of the form {“entity”: {“action”: {array of entity fields}}} in the case of creating and updating an entity, as well as {“entity”: {“action”: “id”}} essence.
Example of an array
{
"leads": {
"status": {
"id": "25399013",
"name": "Lead title",
"old_status_id": "7039101",
"status_id": "142",
"price": "0",
"responsible_user_id": "102525",
"last_modified": "1413554372",
"modified_user_id": "102525",
"created_user_id": "102525",
"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": ["Jason"]
},
{
"id": "1075272",
"name": "Date custom field",
"values": ["1413331200"]
}
]
}
}
}
Example array for tasks
If you complete tasks from the task section with a result, then 2 events will come: closing the task and adding the result. In the event of the completion of the task from the card, 1 event occurs about the completion of the task with the result.
{
"task":{
"update":[
{
"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 - not completed, 1 - complete
"account_id":"77711122",
"created_user_id":"110110",
"last_modified":"2017-07-21 19:00:00",
"responsible_user_id":"110110",
"complete_till":"2017-07-22 23:59:00",
"action_close":"1", // Parameter only for updating tasks. 1 - the task was completed with the current update, 0 - was not completed
"result":{ // The result for the task comes, if it was specified.
"id":"155155155",
"text":"Success"
}
}
]
},
"account":{
"subdomain":"test"
}
}
Expected answer
When sending a request, the information is considered accepted if the code from 100 to 299 is returned in the header of the http response, according to the status codes table w3.org.
The first attempt of sending occurs immediately after the selected action is committed. In the event that the attempt is unsuccessful, there will be a resubmission according to the rules presented in the table below.
Attempt number | Time* | Retry response codes |
---|---|---|
2 | 5 minutes | 0-99, and also 300 and more |
3 | 15 minutes | 0-99, and also 300 and more |
4 | 15 minutes | 499 or 500 to 599 |
5 | 1 hour | 499 or 500 to 599 |
*The time elapsed since the previous attempt.
Adding and Removing WebHooks
Method for adding WebHooks. The limit on the number of active WebHooks is 100.
URL of the method to add webhooks
POST / api / v2 / webhooks / subscribe
URL of the method to delete webhooks
POST / api / v2 / webhooks / unsubscribe
Parameters
Parameter | Description |
---|---|
url | The URL to which notifications should be sent must comply with RFC 2396 |
events | List of events when the WebHooks should be sent |
Response parameters
Parameter | Description |
---|---|
url | The URL to which notifications should be sent must comply with RFC 2396 |
result | Were you able to you sign the url for these events |
_links | Array containing information about the request |
_links/self | An array containing information about the current request |
_links/self/href | Relative URL of the current request |
_links/self/method | The method of the current request |
_embedded | An array containing information adjacent to the request |
_embedded/items | An array containing information for each individual element |
Response Headers contains the following headers:
- Content-Type: application / hal + json
- Runtime-Timestamp: 1508320306
Events
Event name | Description |
---|---|
responsible_lead | The responsible user changed for Lead |
responsible_contact | The responsible user changed for contact |
responsible_company | The responsible user changed for company |
responsible_customer | The responsible user changed for customer |
responsible_task | The responsible user changed for task |
restore_lead | Lead restored from trash |
restore_contact | Contact restored from trash |
restore_company | Company restored from trash |
add_lead | Lead added |
add_contact | Contact added |
add_company | Company added |
add_customer | Customer added |
add_task | task added |
update_lead | Lead updated |
update_contact | Contact updated |
update_company | Company updated |
update_customer | Customer updated |
update_task | task updated |
delete_lead | Lead deleted |
delete_contact | Contact deleted |
delete_company | Company deleted |
delete_customer | Customer deleted |
delete_task | task deleted |
status_lead | Status changed for lead |
note_lead | Note added to lead |
note_contact | Note added to contact |
note_company | Note added to company |
note_customer | Note added to customer |
Add Request example
{
subscribe: [
{
url: https://requestb.in/1hwg3ke1,
events: [
"add_lead",
"add_contact",
"add_company",
"add_customer",
"add_task"
]
}
]
}
Delete Request example
{
unsubscribe: [
{
events: [
"responsible_lead",
"responsible_contact",
"responsible_company",
"responsible_customer",
"responsible_task"
]
}
]
}
Response example
{
_links: {
self: {
href: "/api/v2/webhooks/subscribe",
method: "post"
}
},
_embedded: {
items: [
{
url: https://requestb.in/1hwg3ke1,
result: true
}
]
}
}
Example of integration
$data = array(
'subscribe' => array(
array(
'url' => 'https://requestb.in/1hwg3ke1',
'events' => array(
"responsible_lead",
"responsible_contact",
"responsible_company",
"responsible_customer",
"responsible_task"
)
)
)
);
$subdomain='test'; #Our account - subdomain
#Generate a link for the request
$link='https://'.$subdomain.'.amocrm.com/api/v2/webhooks/subscribe';
/* We need to initiate a request to the server We use the cURL library (supplied with PHP). More about work with this library you can read in the manual. */
$curl=curl_init(); #Save the cURL session descriptor
#Set the necessary options for the cURL session
curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-API-client/1.0');
curl_setopt($curl,CURLOPT_HTTPHEADER,['Accept: application/json']);
curl_setopt($curl,CURLOPT_URL,$link);
curl_setopt($curl,CURLOPT_HEADER,false);
curl_setopt($curl,CURLOPT_POSTFIELDS, http_build_query($data));
curl_setopt($curl,CURLOPT_SSL_VERIFYPEER,0);
curl_setopt($curl,CURLOPT_SSL_VERIFYHOST,0);
$out=curl_exec($curl); #Initiate a request to the API and save the response to a variable
$code=curl_getinfo($curl,CURLINFO_HTTP_CODE);
curl_close($curl);
/* Now we can process the response received from the server. This is an example. You can process the data in your own way. */
$code=(int)$code;
$errors=array(
301=>'Moved permanently',
400=>'Bad request',
401=>'Unauthorized',
403=>'Forbidden',
404=>'Not found',
500=>'Internal server error',
502=>'Bad gateway',
503=>'Service unavailable'
);
try
{
#If the response code is not 200, 201 or 204, we return an error message
if(!in_array($code, [200, 201, 204]))
throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error',$code);
}
catch(Exception $E)
{
die('Error: '.$E->getMessage().PHP_EOL.'Error code: '.$E->getCode());
}
List of WebHooks
A method for obtaining a list of WebHooks.
URL of the method
GET / api / v2 / webhooks
Response parameters
Parameter | Description |
---|---|
id | The unique identifier of the application |
url | The URL to which notifications should be sent must comply with RFC 2396 |
events | List of events for which WebHooks should be sent |
_links | Array containing information about the request |
_links/self | An array containing information about the current request |
_links/self/href | Relative URL of the current request |
_links/self/method | The method of the current request |
_embedded | An array containing information adjacent to the request |
_embedded/items | An array containing information for each individual element |
Response Headers contains the following headers:
- Content-Type: application / hal + json
- Runtime-Timestamp: 1508320306
Events
Event name | Description |
---|---|
responsible_lead | The responsible user changed for Lead |
responsible_contact | The responsible user changed for contact |
responsible_company | The responsible user changed for company |
responsible_customer | The responsible user changed for customer |
responsible_task | The responsible user changed for task |
restore_lead | Lead restored from trash |
restore_contact | Contact restored from trash |
restore_company | Company restored from trash |
add_lead | Lead added |
add_contact | Contact added |
add_company | Company added |
add_customer | Customer added |
add_task | task added |
update_lead | Lead updated |
update_contact | Contact updated |
update_company | Company updated |
update_customer | Customer updated |
update_task | task updated |
delete_lead | Lead deleted |
delete_contact | Contact deleted |
delete_company | Company deleted |
delete_customer | Customer deleted |
delete_task | task deleted |
status_lead | Status changed for lead |
note_lead | Note added to lead |
note_contact | Note added to contact |
note_company | Note added to company |
note_customer | Note added to customer |
Example response
{
_links: {
self: {
href: "/api/v2/webhooks",
method: "get"
}
},
_embedded: {
items: [
{
id: 5881,
url: https://requestb.in/1hwg3ke1,
events: [
"responsible_lead",
"responsible_contact",
"responsible_company",
"responsible_customer",
"responsible_task"
]
}
]
}
}
Example integration
$subdomain='test'; #Our account is a subdomain
#Generate a link for the request
$link='https://'.$subdomain.'.amocrm.com/private/api/v2/webhooks';
We need to initiate a request to the server. We use the cURL library (supplied as part of PHP). More about working with this library you can read in the manual.
$curl=curl_init(); #Save the cURL session descriptor
#Set the necessary options for the cURL session
curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-API-client/1.0');
curl_setopt($curl,CURLOPT_HTTPHEADER,['Accept: application/json']);
curl_setopt($curl,CURLOPT_URL,$link);
curl_setopt($curl,CURLOPT_HEADER,false);
curl_setopt($curl,CURLOPT_SSL_VERIFYPEER,0);
curl_setopt($curl,CURLOPT_SSL_VERIFYHOST,0);
$out=curl_exec($curl); #Initiate a request to the API and save the response to a variable
$code=curl_getinfo($curl,CURLINFO_HTTP_CODE);
curl_close($curl);
Now we can process the response, received from the server. This is an example. You can process the data in your own way.
$code=(int)$code;
$errors=array(
301=>'Moved permanently',
400=>'Bad request',
401=>'Unauthorized',
403=>'Forbidden',
404=>'Not found',
500=>'Internal server error',
502=>'Bad gateway',
503=>'Service unavailable'
);
try
{
#If the response code is not 200 or 204, we return an error message
if($code!=200 && $code!=204)
throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error',$code);
}
catch(Exception $E)
{
die('Error: '.$E->getMessage().PHP_EOL.'Error code: '.$E->getCode());
}