• Home
/
• Working in m3ter - User Guides
/
• Integrations
/
• Setting Up and Managing Native and Notification Integrations

Creating and Managing Destinations

In the Integrations section of the Console, you can create Destinations for your integrations to link to:

• Currently, only webhooks can be designated as the endpoint for an integration:

  • If you've defined a Notification Rule based on a system event, you can link this to a webhook integration Destination as the endpoint for the Notification. See Utilizing Events and Notifications for more details.

• You can specify the type of authentication you want an integration to use when connecting to the Destination:

  • Currently, only the M3TER_SIGNED_REQUEST credentials format can be used as the authentication method used for connecting to a webhook Destination. 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.

When you have created a Destination, you can link an integration or Notification to it and complete your setup.

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

• Creating Destinations

• Managing Destinations

• Webhook Authentication for M3TER_SIGNED_REQUEST

Creating Destinations

To create a Destination:

1. Select Integrations>Destinations. The Destinations page opens and lists any existing Destinations.

2. Select Create destination. The Create page opens.

3. Enter Destination 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 Destination.

• URL for the webhook Destination.

4. In the Credentials panel:

• Credential Type. Method of authentication with the Destination.

  • 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 Destination.

5. Select Create Destination. You are returned to the Destinations Details page. The Destination is now available for linking your integrations or Notifications to it.

Managing Destinations

From the Destinations page, you can edit, view details, or delete a Destination.

To manage Destinations:

1. Select Integration>Destinations. The Destinations page opens and lists any existing Destinations.

2. If you want to edit a Destination select Edit:

3. On the Edit page, make your changes and select Update.

4. If you want to view the details of a Destination, select its NAME hotlink. The Destination Details page opens:

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

• URL

• Destination ID

5. If you want to delete a Destination, select Delete:

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

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

1
POST https://test.com
2
X-m3ter-timestamp: 1688460685310
3
X-m3ter-apikey: testApiKey
4
X-m3ter-signature: a9f9936e662512f943a904f3a71d0141c9bdfbf9fd5496902172864e9333ba15
5
X-m3ter-signaturemethod: HmacSHA256
6
X-m3ter-version: 1
7

8
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"}
9

The payload will be:

1
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\"}"
2

Nodejs Example

1
const crypto = require('crypto');
2

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

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

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

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

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

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

31

Next: Managing Integration Credentials

Additional Support