# Scaleway Topics and Events Webhooks

## When to Use This Skill

* How do I receive Scaleway Topics and Events messages at an HTTP/HTTPS endpoint?
* How do I confirm a Scaleway subscription that is stuck in `Pending`?
* How do I verify a Scaleway message signature (`SigningCertURL`, trust chain)?
* Why does `sns-validator` (or other AWS SNS code) reject Scaleway messages?
* What does Hookdeck do with the subscription confirmation, and what's left for my handler?

## How Delivery Works

Scaleway Topics and Events is Scaleway's "in-house implementation of AWS SNS protocol". An HTTP/HTTPS subscriber receives `POST`s whose body is an SNS-style **JSON envelope**:

* **`SubscriptionConfirmation`** arrives first. The subscription stays `Pending` until you confirm it: "make a request to the `SubscribeURL` using your browser or curl" (form: `https://sns.mnq.{region}.scaleway.com/?Action=ConfirmSubscription&TopicArn=…&Token=…`), or paste the `SubscribeURL` into the console's **Confirm subscription** dialog.
* **`Notification`** carries each published message: `Message` (a string), `MessageId`, `TopicArn`, optional `Subject`, `Timestamp`.
* Every envelope is signed: `SignatureVersion` is always `"1"` (Scaleway: "version 2 is not supported"), with `Signature` and `SigningCertURL`.

Scaleway's docs show only the `SubscriptionConfirmation` envelope. The `Notification` fields above come from the SNS protocol that Scaleway implements. `RawMessageDelivery` is not supported, so the envelope is always present.

## Verification (core)

Scaleway: "Your application should **not** directly trust the certificate pointed to by `SigningCertURL`. Instead, you must validate that this certificate was issued by our trusted Certificate Authority (CA), using the CA trust chain." So, for each message:

1. Download the trust chain once (`https://messaging.s3.fr-par.scw.cloud/fr-par/sns/sns-trust-chain.pem`; the `nl-ams` file is currently identical). It holds the root `Scaleway MnQ Root` (valid to 2032) and the intermediate `Scaleway MnQ` (valid to 5 December 2027).
2. Fetch `SigningCertURL` only over https from an allowed host (`messaging.s3.fr-par.scw.cloud`, the host of the fr-par `SigningCertURL` in Scaleway's docs), with no query string or fragment, and cache it by URL. A 4xx from that host means the message is rejected (401); a network error or 5xx is worth a retry (503).
3. Check that the certificate chains to that root, then RSA-SHA1 verify `Signature` over the SNS canonical string.

```javascript
const crypto = require('crypto');
// Signed fields, in this order; only Subject is optional (skipped when absent or null)
const FIELDS = {
  Notification: ['Message', 'MessageId', 'Subject', 'Timestamp', 'TopicArn', 'Type'],
  SubscriptionConfirmation: ['Message', 'MessageId', 'SubscribeURL', 'Timestamp', 'Token', 'TopicArn', 'Type'],
};
FIELDS.UnsubscribeConfirmation = FIELDS.SubscriptionConfirmation;

function verifySignature(msg, signingCert /* X509Certificate that chains to the trust chain */) {
  // Object.hasOwn: a Type such as "constructor" must not reach Object.prototype
  if (msg.SignatureVersion !== '1' || typeof msg.Type !== 'string' || !Object.hasOwn(FIELDS, msg.Type)) return false;
  let canonical = '';
  for (const k of FIELDS[msg.Type]) {
    if (k === 'Subject' && (msg[k] === undefined || msg[k] === null)) continue;
    if (typeof msg[k] !== 'string') return false;
    canonical += `${k}\n${msg[k]}\n`;
  }
  return crypto.verify('RSA-SHA1', Buffer.from(canonical), signingCert.publicKey, Buffer.from(msg.Signature, 'base64'));
}

```

The chain check (leaf → intermediate → self-signed root, each a CA, each in its validity window) is in the examples: Node uses `X509Certificate.checkIssued` and `verify`, Python uses `cryptography`'s `verify_directly_issued_by`. Don't reach for AWS's `sns-validator`: by default it only accepts certificates hosted on `amazonaws.com`, and it never checks Scaleway's trust chain. See [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/scaleway-topics-and-events-webhooks/references/verification.md).

> **For complete handlers with tests**, see [examples/express/](https://github.com/hookdeck/webhook-skills/tree/main/skills/scaleway-topics-and-events-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/scaleway-topics-and-events-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/scaleway-topics-and-events-webhooks/examples/fastapi/).

**Pin your topics.** A valid signature proves Scaleway sent the message, not that it came from *your* topic: anyone with a Scaleway account can subscribe your URL to their own topic. The examples accept only the ARNs in `SCALEWAY_SNS_TOPIC_ARNS` (403 otherwise), and check this before confirming a subscription. When it's unset they log a warning at startup, because they'll then accept, and confirm subscriptions to, any topic.

## Behind Hookdeck vs Direct

|  | Hookdeck **Scaleway Topics and Events** source | Scaleway calls your server directly |
| --- | --- | --- |
| `SubscriptionConfirmation` | Hookdeck confirms it for you and doesn't forward it | Verify it, check `SubscribeURL`, then GET it |
| `Notification` / `UnsubscribeConfirmation` | Forwarded unchanged (body and headers) | Delivered to you |
| Signature | Verify it in your handler | Verify it in your handler |
| What your handler must do | Verify the signature, pin topics, process `Notification` | All of the left column, plus confirmation |

If Hookdeck can't confirm the subscription, it normally stays `Pending`, and you can confirm it by hand with the `SubscribeURL` from the confirmation request shown in Hookdeck.

Keep verifying the signature in your handler. Signatures cover the envelope, not the transport, so they still verify after Hookdeck forwards, retries or replays a message.

## Message Types

| `Type` | When | What the examples do |
| --- | --- | --- |
| `SubscriptionConfirmation` | An HTTP/S subscription is created (see [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/scaleway-topics-and-events-webhooks/references/setup.md) on when exactly) | Validate `SubscribeURL`, GET it; 200, or 502 if Scaleway doesn't answer 200 |
| `Notification` | A message is published to the topic | Log and acknowledge; dedupe on `MessageId` |
| `UnsubscribeConfirmation` | SNS sends this when a subscription is deleted; Scaleway's docs don't say whether it does | Acknowledge |

Route on the signed body `Type`, not on the `x-amz-sns-message-type` header (Scaleway doesn't document headers, and the header isn't signed). `Message` is whatever the publisher sent: try to parse it as JSON, and check types before reading into it.

## Delivery, Retries and Duplicates

* Standard topics are "at-least-once": "it is possible under rare circumstances that the same message may be received more than once." Deduplicate on `MessageId`. FIFO topics preserve order without duplicates.
* Scaleway doesn't support `DeliveryPolicy` and doesn't document a retry schedule, timeout, source IPs or `Content-Type` (AWS SNS sends `text/plain`). The examples read the raw body for any content type and answer quickly.
* There's no timestamp window by default. Hookdeck retries and replays resend the original envelope, `Timestamp` included. Set `SCALEWAY_SNS_MAX_AGE_SECONDS` to opt in when Scaleway calls you directly.

## Environment Variables

```bash
SCALEWAY_SNS_TRUST_CHAIN_PATH=./sns-trust-chain.pem                       # required, downloaded once
SCALEWAY_SNS_TOPIC_ARNS=arn:scw:sns:fr-par:your-project-id:your-topic      # recommended
SCALEWAY_SNS_CERT_HOSTS=messaging.s3.fr-par.scw.cloud                      # optional (this is the default)
SCALEWAY_SNS_MAX_AGE_SECONDS=0                                             # optional replay window, off

```

## Local Development

```bash
# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 scaleway-topics-and-events --path /webhooks/scaleway-topics-and-events

```

## What Isn't Verified Here

The examples were tested against locally generated certificates that copy Scaleway's layout (root → intermediate → signing certificate), not against a live Scaleway delivery. The canonical string follows AWS SNS SignatureVersion 1, which Scaleway's docs point to. If real messages fail verification, log the failure reason and compare the envelope's fields with the canonical string in [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/scaleway-topics-and-events-webhooks/references/verification.md).

Scaleway's docs disagree about `SigningCertURL`. One sample shows `https://messaging.s3.fr-par.scw.cloud/fr-par/sns/sns_certificate_[certSerialNumber].crt`; two others (the Python SDK and AWS CLI pages) show `http://<REDACTED-URL>/SNStest.crt`. The examples accept only https URLs on an allowed host, so if real deliveries carry an http URL or another host, they fail with "SigningCertURL is not an allowed https URL". Only fr-par's certificate URL appears in the docs; the nl-ams host is assumed to be the same.

## Reference Materials

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/scaleway-topics-and-events-webhooks/references/overview.md) - Envelope fields, message types, what Scaleway does and doesn't document
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/scaleway-topics-and-events-webhooks/references/setup.md) - Creating and confirming an HTTP/S subscription, directly or through Hookdeck
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/scaleway-topics-and-events-webhooks/references/verification.md) - Trust chain, certificate checks, canonical string, debugging