# Guide to Scaleway Topics and Events Webhooks: Features and Best Practices

[Scaleway Topics and Events](https://www.scaleway.com/en/docs/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:

```json
{
  "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](https://inspect.hookdeck.com) 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 `SubscribeURL` from the confirmation into the console to start receiving messages.

## Setting up Scaleway Topics and Events webhooks

1. In the Scaleway console, open **Topics and Events** under **Integration Services** and select the topic's region.
2. Create a topic, or click an existing one.
3. Click **Create Subscription**, choose **HTTPS**, and enter your endpoint URL. The scheme is optional.
4. Click **Create subscription**. The subscription is `Pending` until it's confirmed.
5. Confirm it. Request the `SubscribeURL` from the confirmation message, or open the subscription's menu, choose **Confirm subscription**, and paste the `SubscribeURL` into 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](https://www.scaleway.com/en/docs/topics-and-events/api-cli/connect-aws-cli/) describes, with a profile named `sns`:

```bash
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 `TopicArn` must be `arn:scw:sns:fr-par:...` or `arn:scw:sns:nl-ams:...`.
* The `SubscribeURL` must be `https://sns.mnq.<same region>.scaleway.com/`, with `Action=ConfirmSubscription` and the same `TopicArn` and `Token` as 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:

```bash
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`, `TopicArn` and `Type`.
* **SubscriptionConfirmation and UnsubscribeConfirmation:** `Message`, `MessageId`, `SubscribeURL`, `Timestamp`, `Token`, `TopicArn` and `Type`.

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 `SigningCertURL` directly. 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.pem` for `fr-par`
  * `https://messaging.s3.fr-par.scw.cloud/nl-ams/sns/sns-trust-chain.pem` for `nl-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

```javascript
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:

```javascript
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`](https://cryptography.io/) package, version 42 or later:

```python
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_data())` 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](/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 `SubscribeURL` or 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](/docs/retries), and [issues](/docs/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 `Subject` or on fields inside `Message`.

**How Hookdeck Can Help:** Hookdeck [filters](/docs/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](/docs/transformations) 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](/webhooks/guides/implement-webhook-idempotency).

### Acknowledge fast and process asynchronously

Verify, queue and return `200`, then act in a worker. See [why to process webhooks asynchronously](/webhooks/guides/why-implement-asynchronous-processing-webhooks).

### 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](https://hookdeck.com) confirms Scaleway subscriptions for you and holds each message until your service has processed it.

[Get started with Hookdeck](https://dashboard.hookdeck.com/signup) for free and handle Scaleway Topics and Events webhooks reliably in minutes.