Agent skill

Scaleway Topics and Events Webhooks Skill

Receive and verify Scaleway Topics and Events (SNS-compatible) messages over HTTP/HTTPS. Use when subscribing an HTTP endpoint to a Scaleway topic, confirming a subscription (SubscriptionConfirmation / SubscribeURL), verifying message signatures against Scaleway's CA trust chain (SigningCertURL, sns-trust-chain.pem), or handling Notification envelopes, directly or behind Hookdeck.

Install this skill

npx skills add hookdeck/webhook-skills --skill 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 POSTs 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.
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.

For complete handlers with tests, see examples/express/, examples/nextjs/, 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 sourceScaleway calls your server directly
SubscriptionConfirmationHookdeck confirms it for you and doesn't forward itVerify it, check SubscribeURL, then GET it
Notification / UnsubscribeConfirmationForwarded unchanged (body and headers)Delivered to you
SignatureVerify it in your handlerVerify it in your handler
What your handler must doVerify the signature, pin topics, process NotificationAll 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

TypeWhenWhat the examples do
SubscriptionConfirmationAn HTTP/S subscription is created (see references/setup.md on when exactly)Validate SubscribeURL, GET it; 200, or 502 if Scaleway doesn't answer 200
NotificationA message is published to the topicLog and acknowledge; dedupe on MessageId
UnsubscribeConfirmationSNS sends this when a subscription is deleted; Scaleway's docs don't say whether it doesAcknowledge

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

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

# 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.

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


Repository

hookdeck/webhook-skills

v0.1.0 · MIT · Updated Nov 17, 2026

View on GitHub →