The following Webhooks are currently available in Enate:
PacketCreated - fires when a Ticket, Case or Action is created.
PacketUpdated - fires when a Ticket, Case or Action is updated.
NewCommunication - fires when a communication (email or note) is added to a specific work item
BusinessObjectCreated - fires when a COMPANY or a SCHEDULE is created.
BusinessObjectUpdated - fires when a COMPANY or a SCHEDULE is updated.
SpecificBusinessObjectUpdated - fires when a COMPANY or a SCHEDULE, specified within the subscription, is updated.
The sections below give details for the webhooks you can currently subscribe to, a short description of the events which will trigger them, the data you'll get returned from the webhook (with example values for each) and the parameters which are to be passed in.
Note that the term 'Packet' here refers to Enate's Work Items - which can be of type Case, Action or Ticket.
Name
Packet Created
Related events
Creation of any work item i.e. Case, Action, Ticket
Message returned
Returns basic packet information in JSON format:
{
"CustomerName": the name of the customer e.g. "Globex Corporation",
"SupplierName": the name of the supplier e.g. "Initech",
"ContractName": the name of the contract e.g. "Capital Discovery",
"ServiceName": the name of the service e.g. "HR Relief",
"ServiceLineName": the name of the service line e.g. "East Coast",
"ProcessTypeName": the name of the process type e.g. "Start Employee",
"Reference": this is a system generated identifier for a packet, it follows Enate’s own formatting e.g. "202234-C",
"Title": the title of the packet. This is not set until the packet is submitted when it is set by the user (or whatever is creating the packet) – newly created packets won’t have it yet e.g. “Standard Appeal”,
"Status": the status of the packet. Draft = 0, ToDo = 1, InProgress = 2, Waiting = 3, Resolved = 4, Closed = 5
"DueDate": this is not set until the packet is submitted – newly created packets won’t have it yet e.g. null
"RAGStatus": the RAG status of the packet, e.g. 1. ToBeDetermined = -2, Overdue = -1, DueToday = 0, DueInFuture = 1
"ProcessType": the process type, e.g. 1. Case = 1, Ticket = 2, Action = 3
"GUID": the Webhook GUID e.g. "215d6b04-f587-eb11-b9ad-e86a64437383"
}
Parameters required
"Webhook": name of the WebHook being subscribed to i.e. PacketCreated
"FilterObjectGUID": mandatory filter of identifying GUID for either
· Company (customer)
· Contract
· Service or
· Case/Ticket Process
"FilterObjectType": ID for the type of object being filtered by i.e.
· Company = 31
· Contract = 215
· Service = 217
· Process = 911
"SubscriberURL": a valid URL (inc. http/https") which can receive the WebHook message
"CustomHeader": optional field which adds a custom header to all messages sent by the Webhook subscription – it can be used, for example, to include additional authentication information to ensure incoming messages are genuine, or to enrich incoming messages to make them easier to identify and process. i.e. New-packet-subscription
"CustomHeaderValue": optional field which adds a corresponding value to the custom header to all messages sent by the Webhook subscription – it can be used, for example, to include additional authentication information to ensure incoming messages are genuine, or to enrich incoming messages to make them easier to identify and process i.e. New packet created for Globex Corporation"
Restrictions
The user account creating the subscription must have permission to access data related to the requested entity (Customer, Contract etc.)
Name
PacketUpdated
Related events
Updates to a specified work item
Message returned
Returns basic packet information in JSON format:
{
"CustomerName": the name of the customer e.g. "Globex Corporation",
"SupplierName": the name of the supplier e.g. "Initech",
"ContractName": the name of the contract e.g. "Capital Discovery",
"ServiceName": the name of the service e.g. "HR Relief",
"ServiceLineName": the name of the service line e.g. "East Coast",
"ProcessTypeName": the name of the process type e.g. "Start Employee",
"Reference": this is a system generated identifier for a packet, it follows Enate’s own formatting e.g. "202234-C",
"Title": the title of the packet. This is not set until the packet is submitted when it is set by the user (or whatever is creating the packet) – newly created packets won’t have it yet e.g. “Standard Appeal”,
"Status": the status of the packet e.g. "0". Draft = 0, ToDo = 1, InProgress = 2, Waiting = 3, Resolved = 4, Closed = 5
"DueDate": this is not set until the packet is submitted – newly created packets won’t have it yet e.g. "null"
"RAGStatus": the RAG status of the packet e.g. "-2". ToBeDetermined = -2, Overdue = -1, DueToday = 0, DueInFuture = 1
"ProcessType": the process type e.g. "1". Case = 1, Ticket = 2, Action = 3
"GUID": the Webhook GUID e.g. "215d6b04-f587-eb11-b9ad-e86a64437383"
}
Parameters required
"Webhook": Name of the WebHook being subscribed to i.e. PacketUpdated
"FilterObjectGUID": Mandatory filter of identifying GUID for required packet
"FilterObjectType": "ID for the type of object being filtered by i.e.
· Packet = 81
"SubscriberURL": "A valid URL (inc. http/https") which can receive the WebHook message
"CustomHeader": optional field which adds a custom header to all messages sent by the Webhook subscription – it can be used, for example, to include additional authentication information to ensure incoming messages are genuine, or to enrich incoming messages to make them easier to identify and process. i.e. Update-packet-subscription
"CustomHeaderValue": optional field which adds a corresponding value to the custom header to all messages sent by the Webhook subscription – it can be used, for example, to include additional authentication information to ensure incoming messages are genuine, or to enrich incoming messages to make them easier to identify and process i.e. Packet 200243-C updated"
Restrictions
The user account creating the subscription must have permission to access data related to the requested packet
Note: For Packet Updated you need to supply a packet GUID, so you would use:
FilterObjectType = 81 (Packet in the EnateObjects enum)
FilterObjectGUID = <any valid PacketGUID you can access>
WebHook = PacketUpdated
Name
NewCommunication
Related events
New communications added to a specified work item
Message returned
Returns basic communication information in JSON format:
{
"To": "to" email address
"Importance": 0 = normal, 1 = low, 2 = high
"CC": mail address included in CC
"From": "from" email address if included in the email/message formats
"Subject": pulled from the subject field of the communication, if it has one, e.g. "TPS Reports",
"AttachmentCount": this is the number of attachments on the communication e.g. 30,
"GUID": the Webhook GUID e.g. "31fbfa65-dc39-4c9c-a1f4-47dfef636bea",
"PacketGUID": this identifies the Packet which is being reported on, the GUID in the response when creating a new subscription is the identifier for hat subscription e.g. "878409be-7886-eb11-b9ad-e86a64437383",
"CommunicationType": the communication type used, e.g. 7. EmailOutgoing = 0, PhoneIncoming = 1, EmailIncoming = 2, ESSComment = 3, AuditNote = 4, PhoneOutgoing = 5, LetterIncoming = 6, LetterOutgoing = 7
}
Parameters required
"Webhook": Name of the WebHook being subscribed to i.e. NewCommunication
"FilterObjectGUID": Mandatory filter of identifying GUID for required packet
"FilterObjectType": "ID for the type of object being filtered by i.e.
· Packet = 81
"SubscriberURL": "A valid URL (inc. http/https") which can receive the WebHook message
"CustomHeader": optional field which adds a custom header to all messages sent by the Webhook subscription – it can be used, for example, to include additional authentication information to ensure incoming messages are genuine, or to enrich incoming messages to make them easier to identify and process i.e. new-communication
"CustomHeaderValue":optional field which adds a corresponding value to the custom header to all messages sent by the Webhook subscription – it can be used, for example, to include additional authentication information to ensure incoming messages are genuine, or to enrich incoming messages to make them easier to identify and process i.e. New communication added to 200243-C"
Restrictions
The user account creating the subscription must have permission to access data related to the requested packet
For NewCommunication you need to supply a packet GUID, so you would use:
FilterObjectType = 81 (Packet in the EnateObjects enum)
FilterObjectGUID = <any valid PacketGUID you can access>
WebHook = NewCommunication
A NewCommunication webhook subscription will result in a message being sent whenever a new communication of any sort (a Note, Incoming Email, Outgoing Email etc.) is added to the specified packet.
Name
BusinessObjectCreated
Related events
A new business object of a specified type is created (Object types Company and Schedule are provided in this release)
Message returned
Returns basic object information in JSON format:
{
"Name": name is set by the user, e.g. "2022 Schedule",
"GUID": the Webhook GUID e.g. "a3bc0b28-8023-4ac2-a0c4-2144e8a2d659"
}
Parameters required
"Webhook": Name of the WebHook being subscribed to i.e. NewBusinessObject
"FilterObjectGUID": Mandatory filter of identifying GUID for required packet
"FilterObjectType": "ID for the type of object being filtered by i.e.
· Schedule = 260 or
· Company = 31
"SubscriberURL": "A valid URL (inc. http/https") which can receive the WebHook message
"CustomHeader": optional field which adds a custom header to all messages sent by the Webhook subscription – it can be used, for example, to include additional authentication information to ensure incoming messages are genuine, or to enrich incoming messages to make them easier to identify and process i.e. new-schedule
"CustomHeaderValue": optional field which adds a corresponding value to the custom header to all messages sent by the Webhook subscription – it can be used, for example, to include additional authentication information to ensure incoming messages are genuine, or to enrich incoming messages to make them easier to identify and process i.e. New schedule created"
Restrictions
User must have Process Builder role
For Business Object Created you only need to supply the FilterObjectType, so you would use:
FilterObjectType = 31 (Company in the EnateObjects enum)
WebHook = BusinessObjectCreated
OR
FilterObjectType = 81 (Schedule in the EnateObjects enum)
WebHook = BusinessObjectCreated
Name
BusinessObjectUpdated
Related events
Any existing business object of a specified type is updated (Object types Company and Schedule are provided in this release)
Message returned
Returns basic object information in JSON format: {
"Name": name is set by the user, e.g. "2022 Schedule",
"GUID": the Webhook GUID e.g. "a3bc0b28-8023-4ac2-a0c4-2144e8a2d659"
}
Parameters required
"Webhook": Name of the WebHook being subscribed to i.e. BusinessObjectUpdated
"FilterObjectGUID": Should be left empty
"FilterObjectType": "The type of object being filtered by i.e.
Schedule or
Company
"SubscriberURL": "A valid URL (inc. http/https") which can receive the WebHook message
"CustomHeader": optional field which adds a custom header to all messages sent by the Webhook subscription – it can be used, for example, to include additional authentication information to ensure incoming messages are genuine, or to enrich incoming messages to make them easier to identify and process i.e. updated-company
"CustomHeaderValue": optional field which adds a corresponding value to the custom header to all messages sent by the Webhook subscription – it can be used, for example, to include additional authentication information to ensure incoming messages are genuine, or to enrich incoming messages to make them easier to identify and process i.e. Company details have been updated
Restrictions
User must have Process Builder role
Name
SpecificBusinessObjectUpdated
Related events
A specific business object of a specified type is updated (Object types Company and Schedule are provided in this release)
Message returned
Returns basic object information in JSON format: {
"Name": name is set by the user, e.g. "2022 Schedule",
"GUID": the Webhook GUID e.g. "a3bc0b28-8023-4ac2-a0c4-2144e8a2d659"
}
Parameters required
"Webhook": Name of the WebHook being subscribed to i.e. BusinessObjectUpdated
"FilterObjectGUID": Filter of identifying GUID for required business object
"FilterObjectType": "The type of object being filtered by i.e.
Schedule or
Company
"SubscriberURL": "A valid URL (inc. http/https") which can receive the WebHook message
"CustomHeader": optional field which adds a custom header to all messages sent by the Webhook subscription – it can be used, for example, to include additional authentication information to ensure incoming messages are genuine, or to enrich incoming messages to make them easier to identify and process i.e. updated-company
"CustomHeaderValue": optional field which adds a corresponding value to the custom header to all messages sent by the WebHook subscription – it can be used, for example, to include additional authentication information to ensure incoming messages are genuine, or to enrich incoming messages to make them easier to identify and process i.e. Company details have been updated
Restrictions
User must have Process Builder role
In order to work with Webhooks in Enate, you need to pass certain parameters to the Webhook (see here for more information) and you will get a message returned with corresponding information (see below for more information).
"AttachmentCount"
This is the number of attachments on the communication
"CC"
Email addresses included in the email 'CC' field
"CommunicationType"
The communication type used :
0 = EmailOutgoing
1 = PhoneIncoming
2 = EmailIncoming
3 = ESSComment
4 = AuditNote
5 = PhoneOutgoing
6 = LetterIncoming
7 = LetterOutgoing
"ContractName"
The name of the contract
"CustomerName"
The name of the customer
"DueDate"
This is not set until the packet is submitted – newly created packets won’t have it yet
"From"
'From' email address if included in the email/message formats
"GUID"
The Webhook GUID
"Name"
Name is set by the user
"PacketGUID"
This identifies the packet which is being reported on, the GUID in the response when creating a new subscription is the identifier for hat subscription
"ProcessType"
The process type.
1 = Case
2 = Ticket
3 = Action
"ProcessTypeName"
The name of the process type
"RAGStatus"
The RAG status of the packet.
-2 = ToBeDetermined
-1 = Overdue
0 = DueToday
1 = DueInFuture
"Reference"
This is a system-generated identifier for a packet, it follows Enate’s own formatting
"Sender"
The email address of the sender
"ServiceName"
The name of the service
"ServiceLineName"
The name of the service line
"StartedbyMethod"
The method by which the packet was started.
0 = Workflow
1 = ByOperationalUser
2 = BySelfServiceUser
3 = ByRobotUser
4 = ByEmail
5 = FromTicket
6 = ByOperationalUserInBulk
7 = ByRobotUserInBulk
8 = BySchedule
"Status"
The status of the packet.
0 = Draft
1 = To Do
2 = In Progress
3 = Waiting
4 = Resolved
5 = Closed
"Subject"
This is the pulled from the subject field of the communication, if it has one
"SupplierName"
The name of the supplier
"Title"
The title of the packet. This is not set until the packet is submitted when it is set by the user (or whatever is creating the packet) – newly created packets won’t have it yet
"CustomHeader"
Optional field which adds a custom header to all messages sent by the Webhook subscription – it can be used, for example, to include additional authentication information to ensure incoming messages are genuine, or to enrich incoming messages to make them easier to identify and process.
"CustomHeaderValue"
Optional field which adds a corresponding value to the custom header to all messages sent by the Webhook subscription – it can be used, for example, to include additional authentication information to ensure incoming messages are genuine, or to enrich incoming messages to make them easier to identify and process.
"FilterObjectGUID"
Mandatory field, identifying GUID for whatever object type (FilterObjectType) is required.
"FilterObjectType"
ID for the type of object being filtered by. Company = 31
Contract = 215
Service = 217
Process = 911
"SubscriberURL"
A valid URL (inc. http/https") which can receive the WebHook message
"Webhook"
Name of the WebHook being subscribed to i.e. PacketCreated
For creating subscriptions, the FilterObjectType and the FilterObjectGUID should match up according to the item you want to receive messages about, i.e. if you want to know about Packets Created for a particular Company then you would use:
FilterObjectType = 31 (Company in the EnateObjects enum) (Or alternatively Contract = 215, Service = 217)
FilterObjectGUID = <any valid Company GUID you can access>
WebHook = PacketCreated
A list of commonly asked questions regarding Enate Webhooks.
Q: In the event of the external system being down, or a failure response, does the Enate system retry? A: YES. The Enate system will retry failed messages 3 times.
Q: Is there a possibility of duplicate events? A: YES. Duplicate events can occur, for instance multiple updates to a work item occurring in quick succession, or when an email is received (which triggers a 'new email received' webhook and may very likely then trigger the packet update API too, if incoming email will change the work item's current state.
Q: Is there a standard response structure for Enate Webhooks? A: NO. Response structures can be different between Webhooks. Please see the list of for the specifics of each response structure.
Q: If I've unsubscribed from a Webhook, what is the procedure for re-subscribing. Is there some kind of 'reactivation' approach? A: NO, this is a simple case of adding a subscription again, as you did when first subscribing to it.
Q: Is it mandatory to supply an Entity for a Webhook? A: No. This is dependent upon the Webhook. In some situations it is mandatory, in some optional, and in others there isn't such a filter option.
Q: Can the same subscriber URL be used in multiple subscriptions? A: Yes, it is possible for the same subscriber URL to be used in multiple subscriptions. However, it may be preferable to create different URLs for each subscription to prevent bottlenecks and to create more logical routes for messages into downstream systems.
Q: How can I identify whether the Webhook update is for a Case or Ticket or Action? A: The ProcessType field will indicate the type of packet i.e. 1= Case, 2=Ticket, 3=Action but a more informative approach would be to add some identifying information to the custom header when creating the webhook subscription, this header information will then be included with every message sent out i.e.:
"CustomHeader": " Update-ticket-200243-T-subscription"
"CustomHeaderValue": "Ticket 200243-T has been updated "
Q: Can Webhook Subscriptions be seen by other users? A: Webhook Subscriptions are per user and the permissions of that user are applied to the messages that are sent so, depending on permission configurations, not all users will be able to see all Webhook Subscriptions.
Q: In which scenarios will a New Communication event be triggered for a packet ? A: A New Communication event is triggered whenever a new Packet Communication is written to the database. A Packet Communication may be:
A note written by Agent
A note written in Self Service
An email coming in
An email going out
An existing email being “duplicated” onto another Work Item (for instance a Ticket merge into a Ticket/Case/Action causes a “new” email in the target work item)
Two and three are present under Webhook Subscription. These are the API for the client to consume and subscribe to the webhooks.
Path /WebHookSubscription/GetAllWebhookSubscriptions
Type: GET
Function: Returns a list of all Webhook Subscriptions
No parameters required
Expected Response – list of subscriptions in the following format:
Path: /WebHookSubscription/GetWebhookSubscription
Type: GET
Function: Returns detail of a specific Webhook Subscription
Parameter to set: webhookSubscriptionGUID
Parameter values: GUID value present in GUID column of tblWebhookSubscriptions table.
Expected Response – a single subscription in the following format:
Response Code: 200 :
Expected Response in case of invalid GUID: Response Code:400 - Bad Request The response should contain the below message: ‘The request is invalid’ Request:
Path: /WebHookSubscription/SubscribeToWebhook
Type: POST
Function: Used to create a new subscription and the API returns the details of newly created
Webhook Subscription
Parameters:
Expected Response: Response Code:200 Expected Response – subscription data in the following format:
The signature should be added by the server when the subscription is created and then included in the webhook messages which are sent out.
Takes a Webhook subscription GUID as the only parameter.
Permanently deletes a subscription from the database.
A GET API called Simulate Event is present under Webhook Test.
Parameter: any valid webHookSubscriptionGUID
Creates a test WebHook message for a provided webHookSubscriptionGUID
When an unauthorized request is sent, the APIs need to show a message stating ‘Authorization has been denied for this request’. Below is the response in case of an unauthorised request:
Quick steps to vaidate authorization:
Open the Swagger UI
Do not login to the test instance
Send a request with all the valid details
API throws an error saying Authorization has been denied
Login to the test instance
Retry the same request
API returns successful response as the request is authorized.
When an invalid request is submitted, the APIs need to return 400-Bad Request Error and display a message stating, ‘The request is invalid’. Below is the response in case of invalid requests:
General scenarios where bad request error is seen are mentioned below:
Wrong/Incorrect GUID values
Syntax errors in the Request json
Non existing values
A webhook (also called a web call back or HTTP push API) is a way for an application to provide other applications with real-time information. You can use Webhooks for more seamless integration with your other systems.
You can subscribe to webhooks so your systems are notified of events in Enate as they happen, allowing you to get data immediately. This makes webhooks much more efficient for both provider and consumer. An example might be if a new Case gets created – if this happens then Enate will send a request to your system to let you know.
It's important to be familiar with Webhooks before embarking on using them. You can check out a list of the Webhooks currently available in Enate:
APIs exist in Enate to allow you to get information about the available Webhooks and their structure, and to subscribe / update / unsubscribe from them. A quick example of this would be the . Check out the details for this in the API Webhook Subscription section:
Make sure to check out our sample Webhook integrations section here:
This sections contains common webhook troubleshooting questions to help with any general queries you might have:
You can also check out some of the questions to help with any general queries you might have.
Authentication for creating or updating a Webhook subscription is the same as for any other Enate API, the user account creating the subscription must have the Process Builder role as well as permission to access data related to the requested entity (Customer, Contract etc.). Authentication is required at various points when using Webhook . There are two main places where Webhook authentication takes place:
When the Webhook subscription is created the subscriber needs to provide valid user credentials (as with any other API call) and where the subscription refers to a specific entity (i.e. events related to a Company) the account needs to have permissions on that entity.
Note: This check is also carried out when every Webhook message is being prepared in case the account's permissions have changed since the subscription was originally created).
Every Webhook subscription has a GUID which is generated by the provider when the subscription is created. This is then included in the header of all Webhook messages sent out for that subscription to give the subscriber confidence that the incoming messages are legitimate.
In addition to the above authentication points, Webhook subscriptions have an optional custom http header which can contain any key/value data the subscriber requires i.e. it could be used to include a further key generated by the subscriber which they can use to authenticate received messages.
For the FilterObjectType can be either Company, Contract or Service.
For it can be either Schedule or Company
For or it can only be a Packet (Case/Ticket Process)
- use this to get a list of all available webhooks you can subscribe to.
- use this to get more details for a single kind of subscription.
- use this to subscribe to an individual webhook.
- use this to update an existing subscription to an individual webhook
- use this to permanently delete an existing subscription for an individual webhook.
Note: The subscriber URL is the address of the client that will receive the webhook messages. We can use to get the subscriber URL.
Parameters and response as for plus the GUID of the WebHookSubscription to update
