Sending events via SQS queue

Posting messages to an SQS queue is the recommended method to send events to the Ringier event bus.

Obtaining an SQS queue URL and credentials

When you create or edit a node, enable Emits events and choose Send events to Amazon SQS. You'll be provided with:

Node ID
SQS queue URL
IAM access key
IAM secret key

Posting events to the SQS queue

You can find the AWS SDK and installation instructions here.

The method for sending a message to the SQS queue varies depending on the programming language. Below, you'll find examples for both PHP and JavaScript.

PHP

$message = [
    'events' => ['EventName'],
    'from' => 'NODE_ID',
    'reference' => 'a1f4c8e2-7b93-4d6a-9f2c-8e1d3b5a7c90',
    'created_at' => '2022-05-09T16:59:14+02:00',
    'debounce_key' => 'listing-123456',
    'payload' => [],
    'version' => '2.1.0',
    'route' => ''
];

$client = new SqsClient([
    'region' => 'eu-west-1',
    'version' => 'latest',
    'credentials' => [
    	'key' => 'KEY',
	    'secret' => 'SECRET',
    ],
]);

$params = [
    'MessageBody' => json_encode($message),
    'MessageGroupId' => 'NODE_ID',
    'QueueUrl' => 'QUEUE_URL'
];

try {
    $result = $client->sendMessage($params);
    var_dump($result);
} catch (AwsException $exception) {
    error_log($exception->getMessage());
}

JavaScript

import { SQSClient, SendMessageCommand } from "@aws-sdk/client-sqs"; // ES Modules import
// const { SQSClient, SendMessageCommand } = require("@aws-sdk/client-sqs"); // CommonJS import

const message = {
    'events': ['EventName'],
    'from': 'NODE_ID',
    'reference': 'a1f4c8e2-7b93-4d6a-9f2c-8e1d3b5a7c90',	
    'created_at': '2022-05-09T16:59:14+02:00',
    'debounce_key': 'listing-123456',
    'payload': {},
    'version': '2.1.0',
    'route': ''
  };

const client = new SQSClient({
    region: 'eu-west-1',
    version: 'latest',
    credentials: {
        key: 'KEY',
        secret: 'SECRET',
    },
});

const input = {
  QueueUrl: "QUEUE_URL",
  MessageBody: JSON.stringify(message),
  MessageGroupId: "NODE_ID",
};

const command = new SendMessageCommand(input);

try {
    const response = await client.send(command);
    console.log("Message sent successfully:", response);
} catch (error) {
    console.error("Error sending message:", error);
}

Message parameters

Version 2.1.0 (current)

Name	Type	Required	Description
events	array of strings	✓	Array of event names.
from	string	✓	Your node id. It must be the same as the one used to authenticate.
reference	string	✓	A unique reference for the event instance.
created_at	string	✓	Date and time when the event was created, including timezone, following ISO 8601 (YYYY-MM-DDThh:mm:ss.sTZD), e.g.: "2022-05-09T16:59:14+02:00"
debounce_key	string		Key used to debounce consecutive events. When debouncing is enabled on the emitting node, the bus holds events sharing the same `debounce_key` and only routes the latest one (based on `created_at`). Events without a `debounce_key` are routed as normal. Optional.
payload	object	✓	JSON payload relevant to the specific event(s). See the specifications.
version	string	✓	Event version. The version described here is "2.1.0".
route	string		Together with the event name, this field can be used to determine where the event will be routed. Optional and defaulted to empty. Learn more.

Batch events

To batch events sent to the Bus using SQS, you can use the SQS batch API.

The following example demonstrates how to send two messages in a batch.

PHP

$messages = [
    [
        'Id' => '1',
        'MessageBody' => json_encode($message1),
        'MessageGroupId' => 'NODE_ID',
    ],
    [
        'Id' => '2',
        'MessageBody' => json_encode($message2),
        'MessageGroupId' => 'NODE_ID',
    ],
];

$params = [
    'QueueUrl' => 'QUEUE_URL',
    'Entries' => $messages,
];

try {
    $result = $client->sendMessageBatch($params);
    var_dump($result);
} catch (AwsException $exception) {
    error_log($exception->getMessage());
}

JavaScript

const messages = [
    {
        Id: '1',
        MessageBody: JSON.stringify(message1),
        MessageGroupId: 'NODE_ID',
    },
    {
        Id: '2',
        MessageBody: JSON.stringify(message2),
        MessageGroupId: 'NODE_ID',
    },
];

const input = {
    QueueUrl: "QUEUE_URL",
    Entries: messages,
};

try {
    const response = await client.sendMessageBatch(input);
    console.log("Messages sent successfully:", response);
} catch (error) {
    console.error("Error sending messages:", error);
}

The Id field is used to identify the message in the batch and must be unique within the batch. The structure of the individual messages is the same as when sending a single message.

Multiple events with the same payload

If you want to send several events with the same payload, you can send them in one object.
Example of use case: one user creates an account, ticks the newsletter subscription box and is logged in automatically.


{
    "events": ["UserCreated", "NewsletterSubscribed", "UserLogin"],
    "from": "04f9f5d9-d84c-4636-acae-2067eee4d81f",
    "reference": "a1f4c8e2-7b93-4d6a-9f2c-8e1d3b5a7c90",	
    "created_at": "2022-05-09T16:59:14+02:00",
    "payload": {
      "user": {}
    },
    "version": "2.1.0"
}

Quick links

Event and payload specifications
View events sent
Event routing
Testing