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
| Header | Description |
|---|---|
webhook-id | Unique event ID (e.g. evt_8f3c…). Stays the same across retries. Use it to deduplicate events. |
webhook-timestamp | Unix timestamp (seconds) of this delivery attempt. Changes on every retry. |
webhook-signature | Space-separated list of signatures in the format v1,<base64 signature>. |
Content-Type | application/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.
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).
- Node.js
- Python
// 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)
# pip install standardwebhooks flask
import os
from flask import Flask, request
from standardwebhooks.webhooks import Webhook
webhook = Webhook(os.environ["IMPARGO_WEBHOOK_SECRET"]) # whsec_...
app = Flask(__name__)
@app.post("/impargo/webhooks")
def impargo_webhooks():
try:
event = webhook.verify(request.get_data(), dict(request.headers))
except Exception:
return "Invalid signature", 400
# Deduplicate with request.headers["webhook-id"], then process asynchronously.
print(event["type"], event["data"]["object"]["id"])
return "", 204
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.