Creating and Managing Outgoing Webhooks

In the Integrations section of the Console, you can create Outgoing webhooks:

• If you’ve defined a Notification Rule based on a system event, you can link this to an Outgoing webhook as the endpoint for the Notification and to create a Notification Webhook integration. For more details on creating and configuring Notification Rules, see Utilizing Events and Notifications.
• Currently, only the M3TER_SIGNED_REQUEST credentials format can be used as the authentication method used for connecting to a webhook. See the Webhook Authentication section below for more details on how to work with this format.
• If credentials are not required, then dummy values can be used.

Tip: Integrations Webhook API Example? See Integrations Webhook API Example in our API Reference for a worked example of creating a webhook destination using the API.

This topic explains how to create and manage your integration Outgoing Webhooks. Detailed guidance is also given on how to construct and verify a secure signature for the M3TER_SIGNED_REQUEST:

• Creating Outgoing Webhooks
• Linking Notifications to Outgoing Webhooks
• Managing Outgoing Webhooks
• Webhook Authentication for M3TER_SIGNED_REQUEST

Creating Outgoing Webhooks

To create an Outgoing webhook:

1. Select Integrations:

The Integrations page opens.

2. Select Outgoing webhooks:

The Outgoing webhooks page opens.

3. Select Create outgoing webhook. The Create page opens.
4. Enter Outgoing webhook details:

• Name and Code:
  • Note that when you enter a name and click in the Code field, a default code is entered based on the name you’ve entered, which you can then edit as required.
• Description for the Outgoing webhook.
• URL for the Outgoing webhook.

Important - only valid Domain Name System (DNS) entries permitted! If you enter an invalid DNS entry for URL, then an error message will show when you try to save the Outgoing webhook.

5. In the Credentials panel:

• Credential type. Method of authentication with the Outgoing webhook.
  • Note that only the M3TER_SIGNED_REQUEST authentication method is currently available and the Credential type field is pre-populated with this value.
• Enter the API key and API secret you want use for the M3TER_SIGNED_REQUEST authentication when connecting to the Outgoing webhook.

6. Select Create outgoing webhook. You are returned to the Outgoing webhook details page. The Outgoing webhook is now available for linking your Notifications to it. See Linking Notifications Rules to Outgoing Webhooks for more details.

Linking Notifications to Outgoing Webhooks

To complete your setup for a Notification, you can link a Notification rule to an Outgoing webhook - see Creating, Managing and Reviewing Notifications for more details:

• When you link a Notification rule to an Outgoing webhook, this creates a Notification Webhook integration configuration.
• If an Event of the type on which the Notification rule is based occurs and any conditions you’ve defined using a calculation in the rule are satisfied, then the Notification is triggered and sent to the Outgoing webhook you’ve linked it to.

This section explains how to link Notifications to Outgoing webhooks and how to review and manage those links:

• Linking Notification Rules to Webhooks
• Reviewing and Managing Notifications/Outgoing Webhooks Links

Linking Notification Rules to Webhooks

To link a Notification Rule to an Outgoing webhook:

1. In the Console, select Integrations. The Integrations page opens.
2. Select Outgoing webhooks. The Outgoing webhooks page opens.
3. Select the Name hotlink text of the Outgoing webhook you want to link to a Notification rule to. The Outgoing webhook details page opens.
4. Scroll down the page and on the Linked notification rules panel, select Link notification rules. A Select notification rules dialog appears, and lists the Notification rules created for your Organization.
5. Select the Notification rules you want to link to the Outgoing webhook, and then select Confirm. The dialog closes and the selected Notification rules are listed:

In this example:

• A single Notification rule has been linked to an Outgoing webhook.
• You can read off the Event for the the Notification.
• If you haven’t yet created the Notification rule you want to link to the Outgoing webhook, you can select Create notification rule. This takes you directly to the Create page - see Creating, Managing, and Reviewing Notifications.

6. If you want to review the Notification rule details, select the Name hotlink text. The Notification rule details page opens:

Reviewing and Managing Notifications/Outgoing Webhooks Links

When you’ve linked a Notification rule to an Outgoing webhook, you can review and manage the link:

• If the link is flagged as inactive, check the status.
• Set up Organization users to receive email notifications if the Notification Webhook integration created by the link has been auto-disabled.

To review and manage Notification/Webhook Links:

1. Open the Outgoing webhooks page and select the Name hotlink text of the Outgoing webhook you want to review and manage a Notification/Webhook link for. The Outgoing webhook details page opens.
2. Scroll down the page to the Linked notification rules panel.
3. Select the Details icon for the link you want to review and manage:

The Notification rule / outgoing webhook link modal appears:

• In this example the details modal for an INACTIVE Notification/Webhook link has been opened and an information banner gives the reason why - because the Notification rule configuration is set as globally inactive.
  • If you want to change the status, select Update. The Edit page of the Notification opens.
  • Under Notification rule settings, enable the Active switch and select Update notification rule. You are returned to the Notification rules page where the Notification now shows as ACTIVE.

4. If you want to set up an Organization user to receive an email notification when the Notification Webhook integration created by the link is auto-disabled, use the Disabled notification users drop-down to select the user:

Tip: When is a Notification Webhook Integration Auto-Disabled? See Integration Run Error Handling and Alerts for details.

Managing Outgoing Webhooks

You can edit, view details, or delete an Outgoing webhook.

To manage Outgoing webhooks:

1. Select Integrations. The Integrations page opens.
2. Select Outgoing webhooks:

The Outgoing webhooks page opens.

3. If you want to edit an Outgoing webhook select Edit:

4. On the Edit page, make your changes and select Update outgoing webhook.
5. If you want to view the details of an Outgoing webhook, select its Name hotlink. The Outgoing webhook details page opens:

In this example, Outgoing Webhook 1 details are shown. Note that you can Copy directly to your Clipboard the:

• URL
• API key
• ID

6. If you want to delete an Outgoing webhook, select Delete:

A confirmation dialog appears. Select Yes to confirm the delete action.

Warning! If you try to delete an Outgoing webhook to which you’ve linked a Notification, then you won’t be able to and an error message will show.

Webhook Authentication for M3TER_SIGNED_REQUEST

Currently, the only authentication support for connecting to a webhook is signing a request using an ApiKey and ApiSecret. In m3ter, this is the M3TER_SIGNED_REQUEST credentials format. This format implements a signed request for webhook access and is designed to enable you to build secure webhook endpoints and safeguard them from malicious attacks.

m3ter will sign all the requests it makes to your webhook. When you receive a request on your configured endpoint, you should:

• Validate that the timestamp of the request is within an acceptable grace period.
• Compute the signature based on the information you receive and compare that with the signature m3ter passes. This allows you to verify that the request was made by m3ter and not a third party as bad actor.

You’ll receive the following m3ter headers:

• X-m3ter-timestamp - the timestamp when m3ter made the request.
• X-m3ter-apikey - the apiKey corresponding to the apiSecret used to sign the request.
• X-m3ter-signature - the signature m3ter computed for this request. You need to validate this header.
• X-m3ter-signaturemethod - the algorithm used for computing the signature. Currently, the algorithm used is always HmacSHA256.
• X-m3ter-version - the m3ter signature algorithm. Currently, this is always 1.

Validating the X-m3ter-signature Header

To validate the X-m3ter-signature header, you must prepare a payload String that you sign with your API Secret.

To compute the payload, you must concatenate the following data using a pipe | separator:

• url
• query string - Currently, there’s no support for passing in query parameters. For now, you can hard code to this String: {}
• API Key - provided in the X-m3ter-apikey header.
• timestamp -provided in the X-m3ter-timestamp header.
• body - the request body.

Example

POST https://test.com
X-m3ter-timestamp: 1688460685310
X-m3ter-apikey: testApiKey
X-m3ter-signature: a9f9936e662512f943a904f3a71d0141c9bdfbf9fd5496902172864e9333ba15
X-m3ter-signaturemethod: HmacSHA256
X-m3ter-version: 1

body: {"orgId":"f49e8e22-ddd2-4367-b1ed-761e7e1fbdfd","entityId":"136f7b01-6bbd-4779-88a1-4a22d47b4f97","requestType":"NOTIFICATION","name":"Bill Approved for Locking","description":"Bill approved for locking","accountId":"16c14570-5790-43b5-9ed8-109541b780bb","originalEventId":"8ab97599-02a4-4604-b9fb-e0110ef3dbb9","eventName":"billing.bill.updated","notificationEventId":"679c70ef-f843-4dac-add2-75420666f598","notificationCode":"bill_approved_for_locking"}

The payload will be:

payload = "https://test.com|{}|testApiKey|1688460685310|{\"orgId\":\"f49e8e22-ddd2-4367-b1ed-761e7e1fbdfd\",\"entityId\":\"136f7b01-6bbd-4779-88a1-4a22d47b4f97\",\"requestType\":\"NOTIFICATION\",\"name\":\"Bill Approved for Locking\",\"description\":\"Bill approved for locking\",\"accountId\":\"16c14570-5790-43b5-9ed8-109541b780bb\",\"originalEventId\":\"8ab97599-02a4-4604-b9fb-e0110ef3dbb9\",\"eventName\":\"billing.bill.updated\",\"notificationEventId\":\"679c70ef-f843-4dac-add2-75420666f598\",\"notificationCode\":\"bill_approved_for_locking\"}"

Nodejs Example

const crypto = require('crypto');

// Main function to validate request authenticity
exports.validateSecret = function({ url, queryString, apiKey, apiSecret, timestamp, body, signature }) {  
  var currentTimestamp = Date.now();
  var result = false;

  // Check if the provided timestamp is in the past by comparing it with the current timestamp
  if (currentTimestamp - 30 * 1000 > timestamp) {
    var details = "timestamp in the past: " + currentTimestamp;
    return {"result": result, "log": details};
  }

  // Prepare the payload string by concatenating the request data
  var sharedSecret = apiSecret; // Secret associated with the apiKey
  var safeQueryString = !queryString ? '{}' : queryString;
  var payload = url + "|" + safeQueryString + "|" + apiKey + "|" + timestamp + "|" + body;

  // Generate a cryptographic signature of the payload using HMAC-SHA256
  var sig = crypto.createHmac('sha256', sharedSecret)
    .update(payload)
    .digest('hex');

  // Compare the generated signature with the provided signature using a timing-safe comparison
  result = crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(signature));

  // Return the result and additional information for debugging
  return {"result": result, "log": {"payload": payload, "sig": sig, "signature": signature}};
};