Register for Webhooks Integrations

Endpoints

Webhooks interact with the following endpoint paths which all contain a byRef flag. Setting the flag to "true" will cause the endpoint to expect external reference IDs, while setting it to "false" will cause the endpoint to expect numeric IDs.

For example, you can submit the result of the GET /object/webhooks/{id} endpoint to the PUT /object/webhooks/{id} endpoint and update the corresponding webhooks (provided both requests use the same byRef value). 

Payload for Adding and Updating Third Party Tools 

Some guidelines for integrating external tools through Webhooks:

• The endpoint will need to be an https:// URL to work properly.
• When byRef is true, "external-ref-id-or-id-depending-on-byRef" is the external ref ID string for the entity. When byRef is false, it’s an integer that does not require quotation marks. 
• You can configure each webhook notification to include multiple properties for a single event type.
• If the ID or external ref ID for an object type, field, trigger, role, or group is not found, you'll receive an error message instead of creating a webhook.
• For events that will include object details, the returning section allows you to include specific fields or formulas.

An example of an event where a user is added to an org:

{
  "events": [
    {
      "id": "6-0beb74d6-62d4-5e69-a79b-b4bb32d35677",
      "created": "2021-11-10T21:16:52.99624619Z",
      "category": "Infrastructure",
      "subcategory": "OrgUserMembership",
      "org": 6,
      "meta": {},
      "payload": {
        "OldUser": {
          "first_name": "",
          "all_access": false,
          "reason": "",
          "expiry_date": "0001-01-01T00:00:00Z",
          "last_name": "",
          "email": "",
          "external_ref_id": "",
          "user_type": 0,
          "is_active": false,
          "id": 0,
          "sso_bypass": false,
          "accepted_tos": false,
          "deleted": "0001-01-01T00:00:00Z",
          "admin_email_to_notify": "",
          "super_admin": false,
          "lang": "",
          "exclude_from_membership_count": false
        },
        "NewUser": {
          "user_type": 0,
          "accepted_tos": false,
          "reason": "",
          "admin_email_to_notify": "",
          "email": "my_email@email_domain.com",
          "external_ref_id": "99e0c3df-b95f-4ca6-a325-751cbc12fd39",
          "super_admin": false,
          "sso_bypass": false,
          "is_active": true,
          "exclude_from_membership_count": true,
          "id": 93,
          "first_name": "My First Name",
          "last_name": "my Last Name",
          "lang": "en-US",
          "all_access": false,
          "deleted": "0001-01-01T00:00:00Z",
          "expiry_date": "0001-01-01T00:00:00Z"
        },
        "kind": "Create"
      }
    }
  ],
  "id": "928fdb37803e83f28dbf0e4412b13a2fc19efbb6fd737a8adc1b41290be2cad0"
}

Retrieving Webhooks Example

When you retrieve a webhook from the server, it will include the Id, the ExternalRefId, and the byRef values. This format allows users to copy the response, make necessary edits, and paste it into the updated endpoint, which will ignore the exampleExternalRefId and exampleId values. So, if you change the example value, there is no need to update exampleExternalRefId and exampleId). 

{
  "name": "Example Name",
  "endpoint": "previous endpoint data",
  "events": [{
    type: "ADD_OBJECT",
    criteria: [{
      objectType: "(integer id or external ref id, depending on byRef data)",
      objectTypeId: 123,
      objectTypeExternalRefId: "the external ref of the selected object type"
    }],
    returning: {
      fields: ["(integer id or external ref id, depends on byRef)"],
      formulas: ["(integer id or external ref id, depends on byRef)"]
    }
  }],
  // And some generic core stuff
  "id": 123,
  "externalRefId": "1234-1234-1234-1234",
  "created": "date of creation",
  "modified": "either a time value or null"
}