Skip to main content

Verifying signatures

Every request is signed with the secret of the webhook, following the Standard Webhooks specification. Always verify the signature before processing an event.

Headers​

HeaderDescription
webhook-idUnique event ID (e.g. evt_8f3c…). Stays the same across retries. Use it to deduplicate events.
webhook-timestampUnix timestamp (seconds) of this delivery attempt. Changes on every retry.
webhook-signatureSpace-separated list of signatures in the format v1,<base64 signature>.
Content-Typeapplication/json

The signature is an HMAC-SHA256 over <webhook-id>.<webhook-timestamp>.<raw body>. The key is the base64-decoded part of the secret after the whsec_ prefix.

caution

Verify against the raw request body. Parsing and re-serializing the JSON before verifying breaks the signature.

Using the official libraries​

The standardwebhooks libraries verify the signature and reject requests with a timestamp older than 5 minutes (replay protection).

// npm install standardwebhooks express
const express = require('express')
const { Webhook } = require('standardwebhooks')

const webhook = new Webhook(process.env.IMPARGO_WEBHOOK_SECRET) // whsec_...
const app = express()

app.post('/impargo/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
let event
try {
event = webhook.verify(req.body.toString(), req.headers)
} catch (err) {
return res.status(400).send('Invalid signature')
}

// Deduplicate with req.headers['webhook-id'], then process asynchronously.
console.log(event.type, event.data.object.id)
res.sendStatus(204)
})

app.listen(3000)

Libraries for Go, Java, C#, Ruby, PHP and Rust are listed in the Standard Webhooks repository.

Rolling the secret​

You can roll the secret of a webhook in CargoApps (Roll secret). The new secret is shown once. The old secret stays valid for 24 hours. During that time every request carries two signatures in webhook-signature, so you can switch to the new secret without downtime.