fastify-x-signwell
xSignwell.webhooks.verifySignature
Verify the HMAC-SHA256 signature on an incoming SignWell webhook request using timing-safe comparison.
xSignwell.webhooks.verifySignature
Verify that an incoming webhook request genuinely originated from SignWell by checking its HMAC-SHA256 signature. Uses timingSafeEqual to prevent timing attacks. Always call this before processing any webhook payload.
Signature
fastify.xSignwell.webhooks.verifySignature(
payload: string,
signature: string,
secret: string
): boolean
Params
| Name | Type | Required | Description |
|---|---|---|---|
payload | string | Yes | Raw request body string (not parsed JSON). |
signature | string | Yes | Value from the SignWell signature header. |
secret | string | Yes | Webhook secret from SignWell dashboard. |
Returns
boolean — true if the signature is valid, false otherwise. Uses timingSafeEqual to prevent timing attacks.
Throws
[xSignwell] webhooks.verifySignature: payload (string) is required[xSignwell] webhooks.verifySignature: signature (string) is required[xSignwell] webhooks.verifySignature: secret (string) is required
Examples
Verify before processing
const isValid = fastify.xSignwell.webhooks.verifySignature(
rawBody,
request.headers["x-signwell-signature"],
process.env.SIGNWELL_WEBHOOK_SECRET
);
if (!isValid) {
return reply.code(401).send({ error: "Invalid signature" });
}
Realistic — secure webhook handler
fastify.post("/webhooks/signwell", {
config: { rawBody: true }, // requires rawBody plugin or equivalent
}, async (request, reply) => {
const signature = request.headers["x-signwell-signature"];
const rawBody = request.rawBody;
const isValid = fastify.xSignwell.webhooks.verifySignature(
rawBody,
signature,
process.env.SIGNWELL_WEBHOOK_SECRET
);
if (!isValid) {
return reply.code(401).send({ error: "Invalid signature" });
}
const event = fastify.xSignwell.webhooks.parseEvent(request.body);
// handle event...
return reply.send({ received: true });
});
See also
- webhooks.parseEvent — parse the verified payload into a structured event object
- webhooks.create — register webhook endpoints
AI Context
package: "@xenterprises/fastify-xsignwell"
method: fastify.xSignwell.webhooks.verifySignature(payload, signature, secret)
use-when: Verify HMAC-SHA256 signature on an incoming SignWell webhook request before processing the payload
params: payload (raw body string), signature (from x-signwell-signature header), secret (from SignWell dashboard)
returns: boolean — true if valid, false otherwise; uses timingSafeEqual to prevent timing attacks