Skip to main content

Integrating with Messaging Gateway

Equinix Messaging Gateway is an event-driven solution by Equinix for system-to-system integration between an in-house application to Platform Equinix. EMG leverages queuing solution to provide notifications for latest status on your assets.

Notification Types and Permissions

Required Permissions:

To use Messaging Gateway, you must have below permissions for the required Equinix IBX data centers. If you are unaware of your user permissions, contact your Company Administrator. You can find these permissions under Administration & Ordering permission catalog of Equinix Customer Portal (customerportal.equinix.com)

Notification Workflow

The following diagram illustrates a high-level workflow of how the Messaging Gateway works using queues for Equinix notifications.

  • Equinix IT Systems & Services monitors Equinix Data Center. They trigger internal alerts for planned & unplanned maintenance and incidents.

  • Once the message is processed. Equinix creates a notification message with details of the maintenance & incident. The response message will be pushed into a customer outgoing queue.

  • The customer processes the incoming message.

Authentication Methods

To use the Messaging Gateway, you have valid user credentials to access the Customer Portal.

You can choose the preferred authentication method for your application that subscribes to the Messaging Gateway. The following authentication methods are available:

  • Access Token
  • Certificate-based Authentication

Access Token

To use an access token, follow the steps in the API Authentication documentation to generate a Consumer Key (Client ID) and Consumer Secret (Client Secret). This Consumer Key and Secret must be generated for a user who has access to all customer assets and permission to submit tickets with Equinix. You will then share the Consumer Key and Secret when you create a subscription to the Messaging Gateway.

Certificate (RSA-SHA256)

Equinix supports certificate-based authentication as a part of the EMG subscription. This method requests the primary and secondary public keys to authenticate your data.

The certificate is signed using a secure hashing algorithm (SHA256) with an RSA signature to help you encrypt and decrypt information. You create a public-private key pair and then share the public key with Equinix. The public key is used for encryption, and the private key is used for decryption.

To generate a signature using RSA-SHA256 encryption, you need the EMG message and your private key. Pass the encrypted value in the Signature field in the EMG message after successful generation.

Sample Request:

{  
  "Task": {
    "Id": "bf9f2707-d612-4d63-9958-4c8b1fcf3cc0",
    "Source": "3e095d30-40ff-11e9-8959-5be078353003",
    "Verb": "Create",
    "Resource": "SmartHands",
    "ContentType": "application/json",
    "Version": "1.0",
    "Body": {
      "RequestorId": "123456789",
      "RequestorIdUnique": true,
      "Operation": "0001",
      "Description": "Create SmartHands Order",
      "Attachments": [
        {
          "Name": "samplepicture.jpeg",
          "Url": "https://eqixazurestorage.blob.core.windows.net/file-download-blob/samplepicture.jpeg"          
        }
      ],       
      "Location": "LD8:00:000000",
      "CustomerContact": "demo@equinix.com",
      "SchedulingDetails": {
        "RequestedStartDate": null,
        "RequestedCompletionDate": null
      }
    }
  },
  "Signature": "RWNobwp7CiAgIklkIjogIjM1MGFlZjcwLTc4MWItMTFlOSogIH0KfQ=="
}

How to generate a signature (Mandatory):

  1. Create an RSA-SHA256 signature.
  2. Stringify the Task object.
  3. Update the signature using the stringified task object.
  4. Compute the signature using your private key and encode using base64 encoding.

How to verify the signature (Optional):

  1. Create a verifier using the RSA-SHA256 signature scheme.
  2. Update the verifier with the Task string in the incoming message.
  3. Verify using Equinix public key and base64 encoded signature from the incoming message.

Templates

You can refer Equinix Messaging Gateway Templates to integrate with Equinix Messaging Gateway. The Templates provide sample code for customers to integrate with EMG for Equinix Notifications flows.

The Templates are available under MIT License via GitHub. Since Equinix Messaging Gateway Templates are available under MIT License, you can refer, use, modify & extend these Templates based on your organization architecture & security policies.

There are 3 flavors of the Templates - Java, Node.JS & Python.