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

  • To-do

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:

  1. Adding WebHook

  2. Associating the WebHook with the workflows.

  3. Test integration.

To create a WebHook:

  1. Go to Settings > Integration.

  2. In the Your Integrations section, click "Webhooks".

  3. Enter the WebHook URL.

  4. Select the trigger when the notification will be sent.

  5. Click "Save".

To test the integration

  1. Perform the action selected when creating the WebHook.

  2. In your application, check the data from amoCRM.

  3. 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
  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": ["Jason"]
  35.                 },
  36.                 {
  37.                     "id": "1075272",
  38.                     "name": "Date custom field",
  39.                     "values": ["1413331200"]
  40.                 }
  41.             ]
  42.         }
  43.     }
  44. }
Example array for to-dos

If you complete to-dos from the to-do section with a result, then 2 events will come: closing the to-do and adding the result. In the event of the completion of the to-do from the card, 1 event occurs about the completion of the to-do with the result.

  1. {  
  2.    "to-do":{  
  3.       "update":[  
  4.          {  
  5.             "id":"11122233",
  6.             "element_id":"33322211",
  7.             "element_type":"2",
  8.             "to-do_type":"1",
  9.             "date_create":"2017-07-20 15:00:00",
  10.             "text":"Follow-up",
  11.             "status":"1", // 0 - not completed, 1 - complete
  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", // Parameter only for updating to-dos. 1 - the to-do was completed with the current update,
  18. 0 - was not
  19. completed
  20.             "result":{  // The result for the to-do comes, if it was specified.
  21.                "id":"155155155",
  22.                "text":"Success"
  23.             }
  24.          }
  25.       ]
  26.    },
  27.    "account":{  
  28.       "subdomain":"test"
  29.    }
  30. }
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_to-do The responsible user changed for to-do
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_to-do to-do added
update_lead Lead updated
update_contact Contact updated
update_company Company updated
update_customer Customer updated
update_to-do to-do updated
delete_lead Lead deleted
delete_contact Contact deleted
delete_company Company deleted
delete_customer Customer deleted
delete_to-do to-do 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
  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_to-do"
  11.          ]
  12.       }
  13.    ]
  14. }
Delete Request example
  1. {
  2.    unsubscribe: [
  3.       {
  4.          events: [
  5.             "responsible_lead",
  6.             "responsible_contact",
  7.             "responsible_company",
  8.             "responsible_customer",
  9.             "responsible_to-do"
  10.          ]
  11.       }
  12.    ]
  13. }
Response example
  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. }
Example of integration
  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_to-do"
  11.          )
  12.       )
  13.    )
  14. );
  15. $subdomain='test'; #Our account - subdomain
  16. #Generate a link for the request
  17. $link='https://'.$subdomain.'.amocrm.com/api/v2/webhooks/subscribe';
  18. /* We need to initiate a request to the server We use the cURL library (supplied with PHP). More about
  19. work with this
  20. library you can read in the manual. */
  21. $curl=curl_init(); #Save the cURL session descriptor
  22. #Set the necessary options for the cURL session
  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); #Initiate a request to the API and save the response to a variable
  32. $code=curl_getinfo($curl,CURLINFO_HTTP_CODE);
  33. curl_close($curl);
  34. /* Now we can process the response received from the server. This is an example. You can process the data in your own way. */
  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.   #If the response code is not 200, 201 or 204, we return an error message
  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('Error: '.$E->getMessage().PHP_EOL.'Error code: '.$E->getCode());
  55. }

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_to-do The responsible user changed for to-do
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_to-do to-do added
update_lead Lead updated
update_contact Contact updated
update_company Company updated
update_customer Customer updated
update_to-do to-do updated
delete_lead Lead deleted
delete_contact Contact deleted
delete_company Company deleted
delete_customer Customer deleted
delete_to-do to-do 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
  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_to-do"
  19.             ]
  20.          }
  21.       ]
  22.    }
  23. }
Example integration
  1. $subdomain='test'; #Our account is a subdomain
  2. #Generate a link for the request
  3. $link='https://'.$subdomain.'.amocrm.com/private/api/v2/webhooks';
  4. We need to initiate a request to the server. We use the cURL library (supplied as part of PHP). More about
  5. working with this
  6. library you can read in the manual .
  7.  
  8. $curl=curl_init(); #Save the cURL session descriptor
  9. #Set the necessary options for the cURL session
  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); #Initiate a request to the API and save the response to a variable
  19. $code=curl_getinfo($curl,CURLINFO_HTTP_CODE);
  20. curl_close($curl);
  21. Now we can process the response, received from the server. This is an example. You can process the data in your own way.
  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.   #If the response code is not 200 or 204, we return an error message
  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('Error: '.$E->getMessage().PHP_EOL.'Error code: '.$E->getCode());
  43. }