Guide to Scaleway Topics and Events Webhooks: Features and Best Practices
Scaleway Topics and Events is Scaleway's managed publish/subscribe service. It uses Scaleway's own implementation of the AWS SNS protocol, so you publish messages to a topic and every subscription to that topic receives them. An HTTP or HTTPS subscription turns each message into a request to your endpoint. That makes it a simple way to fan events out from Scaleway workloads to your own services.
This guide covers HTTP and HTTPS subscriptions, the confirmation handshake and how Hookdeck answers it, verifying message signatures against Scaleway's certificate chain, and what Scaleway leaves undocumented.
What are Scaleway Topics and Events webhooks?
A topic is a channel in one region. Publishers send messages to it with the AWS CLI or an AWS SDK pointed at Scaleway's endpoint. Subscribers receive every message published to the topic. A subscriber can be a Scaleway Serverless Function or Container, a Scaleway queue, or an HTTP or HTTPS endpoint, which is the webhook case.
An HTTP or HTTPS subscription starts out Pending. Scaleway sends a SubscriptionConfirmation message to the endpoint, and the subscription only receives messages once someone requests the SubscribeURL in it. Every message carries a signature you can check with a certificate that Scaleway publishes.
Topics come in two types. Standard topics deliver at least once, with best-effort ordering, so a message can occasionally arrive twice. FIFO topics keep messages in order and don't deliver duplicates.
Scaleway Topics and Events webhook features
| Feature | Details |
|---|---|
| Configuration | Scaleway console (Integration Services > Topics and Events), or the SNS-compatible API with the AWS CLI or SDKs |
| API endpoint | https://sns.mnq.<region>.scaleway.com |
| Regions | fr-par and nl-ams, the regions Scaleway publishes trust chains for |
| Subscription protocols | HTTP, HTTPS, Serverless Functions and Containers, Queues |
| Confirmation | A SubscriptionConfirmation message with a SubscribeURL. The subscription stays Pending until confirmed |
| Body | The SNS JSON envelope. Raw message delivery isn't supported |
| Signature | SignatureVersion 1 only, verified with the certificate at SigningCertURL |
| Certificate trust | Scaleway's per-region sns-trust-chain.pem. Signing certificates rotate at least once a year |
| Filter, delivery and redrive policies | Not supported |
| Retries, timeout, content type, source IPs | Not documented |
Messages and payloads
Scaleway's docs show the confirmation message an HTTP or HTTPS endpoint receives:
{
"Type": "SubscriptionConfirmation",
"Token": "<REDACTED-CONFIRMATION-TOKEN>",
"MessageId": "<REDACTED-MESSAGE-ID>",
"TopicArn": "arn:scw:sns:fr-par:<REDACTED-ID>:MyTopic",
"Message": "You have chosen to subscribe to the topic arn:scw:sns:fr-par:<REDACTED-ID>:MyTopic.\nTo confirm the subscription, visit the SubscribeURL included in this message.",
"Timestamp": "2022-06-29T10:03:34Z",
"SignatureVersion": "1",
"Signature": "<REDACTED-SIGNATURE>",
"SigningCertURL": "https://messaging.s3.fr-par.scw.cloud/fr-par/sns/sns_certificate_[certSerialNumber].crt",
"SubscribeURL": "<THE-CONFIRMATION-LINK>"
}
SubscribeURL has the form https://sns.mnq.<region>.scaleway.com/?Action=ConfirmSubscription&TopicArn=<topic ARN>&Token=<token>.
Scaleway doesn't publish a sample of an ordinary message. It implements the SNS protocol, and its docs point to AWS's signature documentation, so expect the SNS notification envelope. That has Type: "Notification", MessageId, TopicArn, Subject when the publisher set one, Message, Timestamp, SignatureVersion, Signature and SigningCertURL. Your payload is the Message string, exactly as the publisher sent it. If you publish JSON, parse Message a second time.
Publishers can set Message, Subject, MessageAttributes and, on FIFO topics, MessageDeduplicationId. Scaleway doesn't say whether message attributes appear in HTTP deliveries. A message published to a topic with no subscriptions is deleted, so subscribe before you publish.
Inspect Scaleway messages as they arrive. Subscribe a Hookdeck Inspect URL to a topic to see the confirmation message and each delivery with its full headers and body, with no account or setup required. Copy the
SubscribeURLfrom the confirmation into the console to start receiving messages.
Setting up Scaleway Topics and Events webhooks
- In the Scaleway console, open Topics and Events under Integration Services and select the topic's region.
- Create a topic, or click an existing one.
- Click Create Subscription, choose HTTPS, and enter your endpoint URL. The scheme is optional.
- Click Create subscription. The subscription is
Pendinguntil it's confirmed. - Confirm it. Request the
SubscribeURLfrom the confirmation message, or open the subscription's menu, choose Confirm subscription, and paste theSubscribeURLinto the box.
The confirmation is a POST that may have no Origin header. Scaleway's troubleshooting page says to make sure your framework accepts a request without one rather than returning 403, which origin and CSRF checks can do.
To test the subscription, publish a message with the AWS CLI configured for Scaleway as Scaleway's AWS CLI guide describes, with a profile named sns:
aws sns publish --profile sns \
--topic-arn "arn:scw:sns:fr-par:<project-id>:MyTopic" \
--subject "test" \
--message '{"hello": "world"}'
With Hookdeck
Create a source with the Scaleway Topics and Events type and use its URL as the subscription endpoint. Hookdeck answers the confirmation for you, so the subscription becomes Confirmed without the console step. Refresh the subscriptions list to check.
When a POST arrives with x-amz-sns-message-type: SubscriptionConfirmation, Hookdeck parses the body and checks it before confirming:
- The
TopicArnmust bearn:scw:sns:fr-par:...orarn:scw:sns:nl-ams:.... - The
SubscribeURLmust behttps://sns.mnq.<same region>.scaleway.com/, withAction=ConfirmSubscriptionand the sameTopicArnandTokenas the body.
Hookdeck then sends a GET to the SubscribeURL as given, with redirects refused and a 5-second timeout. If Scaleway answers 200, Hookdeck returns 200. The confirmation isn't recorded as a request or delivered to your service. If any check fails or Scaleway answers anything else, Hookdeck returns 500 and records the request as rejected with an Ingestion Fatal Error. Open that request in Hookdeck, copy its SubscribeURL, and paste it into the console's Confirm subscription box.
Notifications and unsubscribe confirmations are forwarded to your service unchanged, headers included. The source accepts POST only.
Use the Scaleway type rather than a generic or AWS SNS source. Those types check for AWS hosts, so they won't confirm a Scaleway subscription.
For local development, point the subscription at a Hookdeck source and run:
npx hookdeck-cli listen 3000 scaleway-topics-and-events --path /webhooks/scaleway
Securing Scaleway Topics and Events webhooks
Scaleway signs every message with SignatureVersion 1. Version 2 isn't supported. Scaleway points to AWS's documentation for the signing scheme, and that describes version 1 as an RSA signature with SHA1 over a "string to sign" built from the message's fields:
- Notification:
Message,MessageId,Subject(only if present),Timestamp,TopicArnandType. - SubscriptionConfirmation and UnsubscribeConfirmation:
Message,MessageId,SubscribeURL,Timestamp,Token,TopicArnandType.
Each field contributes its name, a newline, its value and a newline, in that order. The Signature field is the base64 signature.
Scaleway's own advice on the signing certificate:
- Don't trust the certificate at
SigningCertURLdirectly. Check that it was issued by Scaleway's CA, using the trust chain for the topic's region. Download each chain once and ship it with your service:https://messaging.s3.fr-par.scw.cloud/fr-par/sns/sns-trust-chain.pemforfr-parhttps://messaging.s3.fr-par.scw.cloud/nl-ams/sns/sns-trust-chain.pemfornl-ams
- Cache each signing certificate by its URL, and validate it again only when the URL changes.
- Expect rotation at least once a year. During a rollover, accept any certificate the CA issued, because retries and delayed deliveries can carry the old one.
Each chain file holds a root that's valid until 2032 and an intermediate that expires on 5 December 2027. Download the files again before then, or whenever verification starts failing on a new SigningCertURL.
The documented certificate URLs are all under https://messaging.s3.fr-par.scw.cloud/, so the verifiers below only fetch certificates from that host. One of Scaleway's examples shows an http:// SigningCertURL. Plain HTTP is refused here, so check the URL on a real message first, and keep the host check strict so the verifier never fetches from an address an attacker supplies.
Node.js verification
const crypto = require('node:crypto');
const fs = require('node:fs');
// Downloaded once from Scaleway's docs and shipped with your service.
const TRUST_CHAINS = {
'fr-par': loadPemBundle('./scaleway/fr-par-sns-trust-chain.pem'),
'nl-ams': loadPemBundle('./scaleway/nl-ams-sns-trust-chain.pem'),
};
const CERT_HOST = 'messaging.s3.fr-par.scw.cloud';
const SIGNED_KEYS = {
Notification: ['Message', 'MessageId', 'Subject', 'Timestamp', 'TopicArn', 'Type'],
SubscriptionConfirmation: ['Message', 'MessageId', 'SubscribeURL', 'Timestamp', 'Token', 'TopicArn', 'Type'],
UnsubscribeConfirmation: ['Message', 'MessageId', 'SubscribeURL', 'Timestamp', 'Token', 'TopicArn', 'Type'],
};
const certCache = new Map();
function loadPemBundle(path) {
const pems = fs.readFileSync(path, 'utf8').match(/-----BEGIN CERTIFICATE-----[\s\S]+?-----END CERTIFICATE-----/g) || [];
return pems.map((pem) => new crypto.X509Certificate(pem));
}
function isCurrent(cert) {
const now = Date.now();
return now >= Date.parse(cert.validFrom) && now <= Date.parse(cert.validTo);
}
function stringToSign(message) {
if (!Object.hasOwn(SIGNED_KEYS, message.Type)) return null;
const keys = SIGNED_KEYS[message.Type];
let out = '';
for (const key of keys) {
if (key === 'Subject' && message.Subject == null) continue;
if (typeof message[key] !== 'string') return null;
out += `${key}\n${message[key]}\n`;
}
return out;
}
async function signingCert(url, trusted) {
const parsed = new URL(url);
if (parsed.protocol !== 'https:' || parsed.hostname !== CERT_HOST || parsed.port || parsed.search || parsed.hash) return null;
let cert = certCache.get(url);
if (!cert) {
const res = await fetch(url, { redirect: 'error', signal: AbortSignal.timeout(5000) });
if (!res.ok) return null;
cert = new crypto.X509Certificate(Buffer.from(await res.arrayBuffer()));
const issued = trusted.some((ca) => ca.ca && isCurrent(ca) && cert.checkIssued(ca) && cert.verify(ca.publicKey));
if (!issued) return null;
certCache.set(url, cert);
}
return isCurrent(cert) ? cert : null;
}
async function verifyScalewayMessage(message) {
if (!message || typeof message !== 'object' || message.SignatureVersion !== '1') return false;
const region = /^arn:scw:sns:([a-z]+-[a-z]+):/.exec(message.TopicArn ?? '')?.[1];
const trusted = TRUST_CHAINS[region];
const data = stringToSign(message);
if (!trusted || !data || typeof message.Signature !== 'string' || typeof message.SigningCertURL !== 'string') {
return false;
}
try {
const cert = await signingCert(message.SigningCertURL, trusted);
if (!cert) return false;
return crypto.verify('RSA-SHA1', Buffer.from(data, 'utf8'), cert.publicKey, Buffer.from(message.Signature, 'base64'));
} catch {
return false;
}
}
The handler reads the body as text, verifies the message, confirms subscriptions when nothing else has, and queues notifications with MessageId as the dedupe key:
const express = require('express');
const app = express();
async function confirmSubscription(message) {
const url = new URL(message.SubscribeURL);
if (url.protocol !== 'https:' || !/^sns\.mnq\.[a-z]+-[a-z]+\.scaleway\.com$/.test(url.hostname)) {
throw new Error('unexpected SubscribeURL');
}
const res = await fetch(url, { redirect: 'error', signal: AbortSignal.timeout(5000) });
if (!res.ok) throw new Error(`confirmation failed with HTTP ${res.status}`);
}
app.post('/webhooks/scaleway', express.text({ type: '*/*' }), async (req, res) => {
let message;
try {
message = JSON.parse(req.body);
} catch {
return res.sendStatus(400);
}
if (!(await verifyScalewayMessage(message))) return res.sendStatus(401);
try {
if (message.Type === 'SubscriptionConfirmation') {
await confirmSubscription(message); // only reached without Hookdeck in front
return res.sendStatus(200);
}
if (message.Type !== 'Notification') return res.sendStatus(200);
if (await alreadyHandled(message.MessageId)) return res.sendStatus(200);
await queue.add('scaleway-message', {
id: message.MessageId,
topic: message.TopicArn,
subject: message.Subject,
message: message.Message,
});
await markHandled(message.MessageId);
} catch {
return res.sendStatus(503);
}
res.sendStatus(200);
});
queue, alreadyHandled and markHandled are placeholders for your queue and dedupe storage. The handler doesn't reject old Timestamp values, because Scaleway doesn't document a window and a delivery replayed through Hookdeck can arrive much later. MessageId is signed, so deduplicating on it also stops a captured message being replayed, for as long as you keep the ID.
Python verification
This uses the cryptography package, version 42 or later:
import base64
import re
import urllib.request
from datetime import datetime, timezone
from urllib.parse import urlsplit
from cryptography import x509
from cryptography.exceptions import InvalidSignature
from cryptography.hazmat.primitives import hashes
from cryptography.hazmat.primitives.asymmetric import padding
CERT_HOST = "messaging.s3.fr-par.scw.cloud"
CONFIRMATION_KEYS = ["Message", "MessageId", "SubscribeURL", "Timestamp", "Token", "TopicArn", "Type"]
SIGNED_KEYS = {
"Notification": ["Message", "MessageId", "Subject", "Timestamp", "TopicArn", "Type"],
"SubscriptionConfirmation": CONFIRMATION_KEYS,
"UnsubscribeConfirmation": CONFIRMATION_KEYS,
}
def load_pem_bundle(path):
with open(path, "rb") as f:
return x509.load_pem_x509_certificates(f.read())
# Downloaded once from Scaleway's docs and shipped with your service.
TRUST_CHAINS = {
"fr-par": load_pem_bundle("scaleway/fr-par-sns-trust-chain.pem"),
"nl-ams": load_pem_bundle("scaleway/nl-ams-sns-trust-chain.pem"),
}
_cert_cache = {}
def _is_current(cert):
now = datetime.now(timezone.utc)
return cert.not_valid_before_utc <= now <= cert.not_valid_after_utc
def _issued_by(cert, ca):
try:
is_ca = ca.extensions.get_extension_for_class(x509.BasicConstraints).value.ca
cert.verify_directly_issued_by(ca)
except (x509.ExtensionNotFound, ValueError, TypeError, InvalidSignature):
return False
return is_ca and _is_current(ca)
def _string_to_sign(message):
keys = SIGNED_KEYS.get(message.get("Type"))
if not keys:
return None
out = ""
for key in keys:
if key == "Subject" and message.get("Subject") is None:
continue
if not isinstance(message.get(key), str):
return None
out += f"{key}\n{message[key]}\n"
return out
def _signing_cert(url, trusted):
parts = urlsplit(url)
if parts.scheme != "https" or parts.hostname != CERT_HOST or parts.port or parts.query or parts.fragment:
return None
cert = _cert_cache.get(url)
if cert is None:
with urllib.request.urlopen(url, timeout=5) as resp:
raw = resp.read()
if raw.lstrip().startswith(b"-----BEGIN"):
cert = x509.load_pem_x509_certificate(raw)
else:
cert = x509.load_der_x509_certificate(raw)
if not any(_issued_by(cert, ca) for ca in trusted):
return None
_cert_cache[url] = cert
return cert if _is_current(cert) else None
def verify_scaleway_message(message) -> bool:
if not isinstance(message, dict) or message.get("SignatureVersion") != "1":
return False
topic_arn = message.get("TopicArn")
match = re.match(r"arn:scw:sns:([a-z]+-[a-z]+):", topic_arn) if isinstance(topic_arn, str) else None
trusted = TRUST_CHAINS.get(match.group(1)) if match else None
data = _string_to_sign(message)
signature, cert_url = message.get("Signature"), message.get("SigningCertURL")
if not trusted or data is None or not isinstance(signature, str) or not isinstance(cert_url, str):
return False
try:
cert = _signing_cert(cert_url, trusted)
if cert is None:
return False
cert.public_key().verify(
base64.b64decode(signature, validate=True),
data.encode("utf-8"),
padding.PKCS1v15(),
hashes.SHA1(),
)
return True
except (InvalidSignature, ValueError, TypeError, OSError):
return False
Pass it the parsed JSON body, for example json.loads(request.get_ in Flask.
Hookdeck's Scaleway source answers the confirmation handshake, but it has no verification settings and doesn't check message signatures. It forwards each notification with its original body, so your service can verify the signature with the code above. Until it does, anyone who learns the source URL can send requests that look like Scaleway messages, so treat the URL as a secret.
Make Scaleway Topics and Events webhooks production-ready. Hookdeck Event Gateway confirms the subscription for you, stores every message, and retries your service on a schedule you control, so a deploy or outage doesn't cost you a message.
Scaleway Topics and Events webhook limitations and pain points
A manual confirmation step
The Problem: A new HTTP or HTTPS subscription receives nothing until it's confirmed, and the confirmation is easy to miss or block.
Why It Happens: Scaleway keeps the subscription Pending until someone requests the SubscribeURL. The confirmation request may have no Origin header, which CSRF and origin checks can reject with a 403.
Workarounds:
- Log or capture the confirmation body, then request the
SubscribeURLor paste it into the console. - Exempt the webhook route from CSRF and origin checks, and verify the signature instead.
How Hookdeck Can Help: Hookdeck's Scaleway source confirms the subscription itself, after checking the SubscribeURL points at Scaleway's API for the topic's region. If confirmation fails, the request is kept so you can confirm it by hand.
Signature verification is on you
The Problem: Checking a message means fetching certificates, validating them against Scaleway's CA chain, and rebuilding SNS's string to sign.
Why It Happens: Scaleway uses the SNS version 1 scheme, rotates the signing certificate at least yearly, and tells you not to trust it directly.
Workarounds:
- Use the verifiers above, with the trust chain files shipped alongside your code.
- Cache certificates by URL, and alert when verification failures rise.
How Hookdeck Can Help: Hookdeck doesn't verify Scaleway signatures, but it keeps each message's original body and headers, so your service can verify a message when Hookdeck delivers or replays it.
Undocumented delivery behaviour
The Problem: You can't plan for failures you can't see.
Why It Happens: Scaleway doesn't support SNS delivery or redrive policies for subscriptions, and doesn't document its retry schedule, timeout, content type or source IPs. It also publishes no sample notification.
Workarounds:
- Respond quickly and process asynchronously.
- Monitor topics with Scaleway Cockpit, and reconcile from the publisher's side if messages matter.
- Capture a real notification before relying on any field beyond
Message.
How Hookdeck Can Help: Hookdeck accepts each message immediately, so delivery doesn't depend on your service being up. It then gives your service its own retries, and issues alert you when deliveries fail.
No filter policies
The Problem: Every subscription receives every message published to its topic.
Why It Happens: Scaleway doesn't support SNS subscription filter policies.
Workarounds:
- Use separate topics for messages that need different consumers.
- Filter in your handler on
Subjector on fields insideMessage.
How Hookdeck Can Help: Hookdeck filters can route or drop messages before they reach your service. Scaleway doesn't document the Content-Type it sends. If the body arrives as text/plain, as AWS SNS sends it, Hookdeck treats it as text, so add a transformation that parses it before filtering on JSON fields.
Best practices
Verify every message
Check the signature against Scaleway's trust chain before acting on a message, and keep the chain files up to date.
Make handlers idempotent
Standard topics deliver at least once. Deduplicate on MessageId, and design each state change so that applying it twice does no harm. See our guide to webhook idempotency.
Acknowledge fast and process asynchronously
Verify, queue and return 200, then act in a worker. See why to process webhooks asynchronously.
Use HTTPS subscriptions
Scaleway recommends HTTPS over HTTP. Messages carry your data, and the confirmation carries a token.
Conclusion
Scaleway Topics and Events delivers topic messages to HTTP and HTTPS subscriptions in the SNS JSON envelope. Each subscription has to be confirmed through its SubscribeURL, and each message is signed with SignatureVersion 1, verified against a certificate that chains to Scaleway's CA. Verify every message, deduplicate on MessageId, return 200 quickly, and capture a real notification, because Scaleway documents little about delivery.
Hookdeck Event Gateway confirms Scaleway subscriptions for you and holds each message until your service has processed it.
Get started with Hookdeck for free and handle Scaleway Topics and Events webhooks reliably in minutes.