Create an Integration

POST Create an Integration

https://api.moltin.com/v2/integrations

Parameters

Headers

Name	Required	Type	Description
Authorization	Required	string	The Bearer token required to get access to the API.

Body

Name	Required	Type	Description
configuration	Required	object	A configuration object.
observes	Required	array	An array of events you want to observe.
enabled	Optional	boolean	Specifies whether the integration is enabled.
integration_type	Required	string	Specifies how the event is delivered. The options are webhook, aws_sqs, or stomp.
description	Required	string	Specifies a description for the integration.
name	Required	string	Specifies the name of the integration.
type	Required	string	Represents the type of object.

Request Examples

curl -X POST https://api.moltin.com/v2/integrations \
     -H "Authorization: Bearer: XXXX" \
     -H "Content-Type: application/json" \
     -d $'{
      "data": {
        "type": "integration",
        "name": "Order shipping notification",
        "description": "Send a shipping notification via email with discount code.",
        "enabled": true,
        "observes": [
          "order.fulfilled"
        ],
        "integration_type": "webhook",
        "configuration": {
          "url": "https://yourwebsite.com/order-created-notification"
        }
      }
    }'

JavaScript SDK

const data = {
    name: "Order shipping notification",
    description: "Send a shipping notification via email with discount code.",
    enabled: true,
    observes: ["order.fulfilled"],
    integration_type: "webhook",
    configuration: {
        url: "https://yourwebsite.com/order-created-notification",
    },
};

// Where `EPCC` is an authenticated client
await EPCC.Integrations.Create(data);

Response Example

201 Created

{
    "data": {
        "id": "8cb9e689-ede7-4f6d-b61a-6aa970d572dd",
        "type": "integration",
        "integration_type": "webhook",
        "name": "Order shipping notification",
        "description": "Send a shipping notification via email with discount code.",
        "enabled": true,
        "configuration": {
            "url": "https://yourwebsite.com/order-created-notification"
        },
        "observes": ["order.fulfilled"],
        "links": {
            "self": "https://api.moltin.com/v2/integrations/8cb9e689-ede7-4f6d-b61a-6aa970d572dd"
        },
        "meta": {
            "timestamps": {
                "created_at": "2018-04-30T09:35:32.202Z",
                "updated_at": "2018-04-30T09:35:32.202Z"
            }
        }
    }
}

Configuration Object

To have events delivered to your system, you must provide specific configuration to a new integration.

note

You can add only five events to the observes array. If you try to add more than five, the following error is returned:

• "You have reached the integration event limit of 5" (API).
• "There was a problem saving your integration" (Commerce Manager).

The content of the configuration object depends on the value of the integration_type.

Integration Type	Configuration Object
webhook	Configuring a webhook
aws_sqs	Configuring an AWS SQS queue
stomp	Configuring a Simple Text Oriented Messaging Protocol (STOMP) queue

Configuring a webhook

Webhooks are delivered using POST to the configured url. You can specify a secret_key to forward to __X-MOLTIN-SECRET-KEY along with the request as a header.

note

X-MOLTIN-INTEGRATION-TRIGGER is also added to the request headers. This allows you to process several events at the same url. This is in the format of an observable event key.

The webhook configuration object has the following structure.

Attribute	Type	Description
url	string	A required URL that the integration fires.
secret_key	string	A optional header. Useful to authenticate the response came from Elastic Path. This is sent as X-MOLTIN-SECRET-KEY.

{
  "url": "https://yourwebsite.com/order-created-notification", // Required
  "secret_key": "secret_key_to_validate_on_your_endpoint" // Optional
}

Configuring an AWS SQS queue

These event types are delivered directly into the specified AWS SQS queue.

The AWS SQS configuration object has the following structure:

Attribute	Type	Description
url	string	The required SQS queue URL.
aws_access_key_id	string	The required AWS access key ID.
aws_secret_access_key	string	The required AWS secret key ID.
region	string	The required AWS region.

{
  "url": "https://sqs.eu-west-1.amazonaws.com/123456789/epcc-external-queue",
  "aws_access_key_id": "****************JIMB",
  "aws_secret_access_key": "************************************HK4o",
  "region": "eu-west-1"
}

Configuring a Simple Text Oriented Messaging Protocol (STOMP) queue

These event types are delivered directly into the specified message queue.

The STOMP configuration object has the following structure:

Attribute	Type	Description
username	string	The username used to authenticate against a STOMP server.
password	string	The password used to authenticate against a STOMP server.
destination	string	The destination in the messaging queuing system.
addresses	string	The addresses that correspond with the destination name.

{
  "username": "epcc-integration-1",
  "password": "****************************CDKn",
  "destination": "/queue/epcc-integrations.order-created",
  "addresses": [
      "stomp+ssl://b-618354a5-e04f-4eff-99c7-734e9d8b91a5-2.mq.us-west-2.amazonaws.com:61614",
      "stomp+ssl://b-618354a5-e04f-4eff-99c7-734e9d8b91a5-1.mq.us-west-2.amazonaws.com:61614"
    ]
}

Related Resources

Concepts

• Integrations

APIs

• Integrations API
• Observable Events

How-to guides

• [Integration Examples](/commerce-cloud/docs/developer/get-started/integration examples.html)