Skip to main content

Create an AWS SQS subscription

Learn how to configure an AWS SQS queue to receive events from the Multicast Notification Service (MNS).

 

Page contents

To enable the Multicast Notification Service to deliver events to your SQS queue you must first configure the queue to:

  • encrypt messages using a customer-managed KMS key, with a policy allowing MNS to use the key for encryption purposes
  • permit MNS to send messages

This tutorial demonstrates the configuration of an SQS queue in:

  • Region: eu-west-2 (the only appropriate region to process and store patient data and the only region supported by MNS)
  • AWS account ID: 121212121212
  • Queue name: test-signal-receive

Follow the steps below, substituting your account ID and queue name as appropriate:

1. Create KMS customer-managed key

Create a new customer-managed KMS key.

Update the key policy to add a statement granting access to MNS so it can encrypt the data being sent to the queue:

{
  "Version": "2012-10-17",
  "Id": "key-consolepolicy-3",
  "Statement": [
    // Pre-existing statement
    {
      "Sid": "Enable IAM User Permissions",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::121212121212:root"
      },
      "Action": "kms:*",
      "Resource": "*"
    },
    // Statement allowing the MNS service to use the key
    {
      "Sid": "AllowMNSLambdaDelivery",
      "Effect": "Allow",
      "Principal": {
        // For Integration environment subscriptions:
        "AWS": "arn:aws:iam::631615744739:role/nhs-mns-events-lambda-delivery"
        // for Production use 
        // arn:aws:iam::758334270304:role/nhs-mns-events-lambda-delivery
      },
      "Action": "kms:GenerateDataKey",
      "Resource": "*"
    }
  ]
}

2. Create SQS queue to receive the event

Create an SQS queue encrypted using an AWS Key Management Service key (SSE-KMS) using the key created above.

Define an Advanced (JSON) Access Policy with a statement allowing MNS to send messages:

{
  "Version": "2012-10-17",
  "Id": "__default_policy_ID",
  "Statement": [
    // Allow MNS to send messages to the queue
    {
      "Effect": "Allow",
      "Principal": {
        // For Integration environment subscriptions:
        "AWS": "arn:aws:iam::631615744739:role/nhs-mns-events-lambda-delivery"
        // For production use arn:aws:iam::758334270304:role/nhs-mns-events-lambda-delivery
      },
      "Action": "SQS:SendMessage",
      // Replace with your Queue ARN: 
      "Resource": "arn:aws:sqs:eu-west-2:121212121212:test-signal-receive"
    }
  ]
}

The queues should:

3. Create the AWS SQS MNS subscription

Create the subscription using the MNS service API:

POST /multicast-notification-service/subscriptions HTTP/1.1
Host: int.api.service.nhs.uk
Content-Type: application/fhir+json
X-Correlation-ID: {UUID}
Authorization: Bearer {ACCESS TOKEN}


{
    "resourceType": "Subscription",
    "status": "requested",
    "reason": "A good descriptive reason for the subscription, useful in future to help track down subscribers",
    "criteria": "eventType=mns-test-signal-1",
    "channel": {
        "type": "message",
        "endpoint": "arn:aws:sqs:eu-west-2:121212121212:test-signal-receive",
        "payload": "application/fhir+json"
    }
}

The subscription request is a FHIR request. The Content-Type header must be set to application/fhir+json. 

The channel.payload value in the request body specifies the format of the event you receive (CloudEvent or FHIR): use application/json for CloudEvent format, application/json+fhir for FHIR R4 format.

Most subscribers (all third-party subscribers) can only create FHIR R4 format subscriptions.

See the Multicast Notification Service API specification for full information about the Create Subscription operation.

Last edited: 24 April 2026 3:51 pm