Webhooks

Webhooks allow external services to be notified when certain events happen. When the specified events happen, we’ll send a POST request to each of the URLs you provide.

Before you Start

You should have Integration rights in your General Access Security role.

You should be familiar with Webhook configuration, payload configuration, and the integration platform. Alemba recommends you seek the assistance of your professional services team when planning to configure your webhooks if you have never configured them before.

About the Alemba Webhook

Webhooks, in the Alemba ASM system, are powerful tools that act as user-defined HTTP callbacks. An HTTP Callback is a way for an app to provide other applications with real-time information. A webhook delivers data to other applications as it happens, meaning you get data immediately. Instead of requiring you to pull information via periodic polling, webhooks push information as specified events occur.

Is it Secure?

Webhook security largely depends on how they are implemented. To ensure the security of webhooks:

• Use HTTPS: Data is encrypted in transit.

• Secret Tokens: A secret token shared between the sender and the receiver can verify that the data is coming from a trusted source.

• Validate Payloads: Always validate incoming payloads for expected structure and data.

• Limit IP Addresses: If possible, whitelist only certain IP addresses to accept incoming requests from.

While webhooks can be made secure with the right practices, it's crucial to implement these security measures to protect your data and systems.

Webhooks can be an essential tool for automating and integrating your workflow with other applications. Think of a webhook as a notification; when specific actions or events occur in Alemba, the webhook triggers and sends data to other applications or services you’ve set it up with, such as Microsoft Project, Smart Sheets, or social networking platforms.

How to Use Webhooks

1. Ensure Permissions: Before setting up a webhook, make sure you have Integration rights within your General Access Security role. If you're new to webhooks, consider consulting with your professional services team.

2. Configure Your Webhook:

   • Navigate to the ADMIN>Integration Menu.

   • Select Webhooks, then click the Add a Webhook button.

   • You'll need to provide a Payload URL (where the data will be sent) and a Secret (for securing your webhook).

   • Choose an entity type and the triggering events for the webhook. You can select from entities such as Call, CMDB item, Knowledge, and others.

3. Customize Your Webhook:

   • Attachments: Include events for attachments (Upload, Update, Delete) with options to filter by attachment name, size, and set a limit on the number of attachments per payload.

   • Inline Images: Configure your webhook to handle inline images within HTML content.

   • Entity Types: Select from various entity types like Call, CMDB item, Person, etc., to specify what kind of events will trigger the webhook.

4. Testing and Validation:

   • After configuration, test your webhook to ensure it's triggering as expected. Monitor the activity log to see which attachments have been included or excluded.

5. Deployment and Monitoring:

   • Once tested, deploy your webhook live. Keep an eye on its operations to troubleshoot any issues that might arise.

Through this setup, Alemba webhooks can significantly enhance your workflow’s efficiency by ensuring real-time data exchange and automation with other systems in your ecosystem.

The Alemba Webhook supports

1. Events for attachments (Upload, Update and Delete)

   This is enabled via a registry key on the System: When the "Include all attachments in payload" option is enabled it will include the attachments of that entity in the payload. Example: { "Action": "Forwarded", "Call": { "Ref": 757, ...omitted for ease of reading } }, "Attachments": [ { "Ref": 1720, "Name": "Test3.txt", "FileSize": 12, "ContentType": "text/plain", "Data": "VGVzdCBjb250ZW50" }, { "Ref": 1719, "Name": "NewTest1.txt", "FileSize": 12, "ContentType": "text/plain", "Data": "VGVzdCBjb250ZW50" } ] }

   Additional Options:

   • "Attachment Name Filter" - Allows the admin to configure regular expressions to filter what attachments get included by their name. multiple regular expressions can be defined separated by a semi colon ";"

   • "Attachment Size Limit" - Allows the admin to configure a max size of attachment to be included. When greater than 0 (no limit), it will filter what attachments get included based on file size (in kilobytes).

   • "Number of Attachments per Payload Limit" - The maximum number of attachments to be included in the payload. When greater than 0 (no limit), it will select the newest (uploaded/updated most recently) attachments, until the limit is reached.

   A new activity log entry will be added for webhooks which indicate what attachments have been included/excluded from the payload.

2. Inline images when they are contained within HTML

3. Events for the following entity types:

   • Call

   • CMDB item

   • Knowledge

   • CMDB Link

   • Person

   • Request

   • Task

Steps to Add a Webhook

When creating a webhook, you are specifying a payload, that is the message and data, that is sent when the triggering event is met. To add a webhook:

1. Access the ADMIN>Integration Menu

2. Click Webhooks

3. Click the Add a Webhook button

4. Enter the following:

   • Payload URL

   • Secret

   • Select the Core Entity Type. You can select from Call, CMDB item, Knowledge, CMDB Link, Person, Request, or Task.

   • Select the Final Entity Type (what kind of call, request, or task, for example)

   • Select the Triggering events for the web hook.

You can specify the Task Type and to drill down to specific sub types if configured to allow all Task Types to be defined as a Webhook trigger:

• Enter the columns to include in the payload, by default, all columns will be included.

• Enter a payload filter that specifies what payloads should be sent, if necessary.

• If you are ready to turn it on, tick the Active checkbox.

• Click the Add Webhook button to save your changes.

Edit a Webhook

You can edit a given webhhook.

BEST PRACTICE

Changes are immediate. It is advisable to take a copy of the data from each field prior to making changes so that if your changes fail, you can roll back the changes easily.

1. From the Main Menu, access Admin>Integrations>Webhook

2. Click Webhook Configuration

3. Click Edit for the Webhook you want to explore

4. Update your webhook with the desired changes

5. Click Save, to save your changes

Delete a Webhook

You can delete a given webhhook.

You cannot undelete a webhook configuration. Changes are immediate. It is advisable to take a copy of the data from each field prior to deleting the webhook so that you can roll back the if necessary.

1. From the Main Menu, access Admin>Integrations>Webhook

2. Click Webhook Configuration

3. Click Edit for the Webhook you want to explore

4. Update your webhook with the desired changes

5. Click Save, to save your changes

View Recent Deliveries

You can also view recent deliveries for a given webhhok in the Recent Deliveries section. Each row is a clickable link.

Troubleshooting and Retry

The webhook logs can confirm the exact reason why Webhooks may not be firing. In addition the web-hook will continue to retry for up to 1 hour. The Webhook status will change to F (Fail) in the event it still does not fire in the 1 hour retry period.

1. From the Main Menu, access Admin>Integrations>Webhook

2. Click Webhook Configuration

3. Click Edit for the Webhook you want to explore

4. Scroll to the bottom of the page and find Recent Deliveries

5. Click the link according to the Time/Date Stamp that you would like to view and to to explore the details.

6. Click the Refresh Icon to refresh the data

7. Options:

   1. Refresh

   2. Redeliver the payload

   3. View Request Details

   4. View Response Details