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:
SubscriptionConfirmationarrives first. The subscription staysPendinguntil you confirm it: "make a request to theSubscribeURLusing your browser or curl" (form:https://sns.mnq.{region}.scaleway.com/?Action=ConfirmSubscription&TopicArn=…&Token=…), or paste theSubscribeURLinto the console's Confirm subscription dialog.Notificationcarries each published message:Message(a string),MessageId,TopicArn, optionalSubject,Timestamp.- Every envelope is signed:
SignatureVersionis always"1"(Scaleway: "version 2 is not supported"), withSignatureandSigningCertURL.
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:
- Download the trust chain once (
https://messaging.s3.fr-par.scw.cloud/fr-par/sns/sns-trust-chain.pem; thenl-amsfile is currently identical). It holds the rootScaleway MnQ Root(valid to 2032) and the intermediateScaleway MnQ(valid to 5 December 2027). - Fetch
SigningCertURLonly over https from an allowed host (messaging.s3.fr-par.scw.cloud, the host of the fr-parSigningCertURLin 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). - Check that the certificate chains to that root, then RSA-SHA1 verify
Signatureover 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_. 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 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 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
DeliveryPolicyand doesn't document a retry schedule, timeout, source IPs orContent-Type(AWS SNS sendstext/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,
Timestampincluded. SetSCALEWAY_to opt in when Scaleway calls you directly.SNS_ MAX_ AGE_ SECONDS
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_; 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 - Envelope fields, message types, what Scaleway does and doesn't document
- references/setup.md - Creating and confirming an HTTP/S subscription, directly or through Hookdeck
- references/verification.md - Trust chain, certificate checks, canonical string, debugging