Steps#
1. Generate a secret and keep it on your server#
Use a long random value, for example openssl rand -hex 32, and store it in your secrets manager next to your client secret.
2. Register the webhook with the secret in headers#
Create the webhook from your server with POST /webhooks (createWebhook in the SDK), passing the secret as a custom header. Pluggy sends that header on every notification. A webhookUrl set on an Item or a Connect Token doesn't send custom headers, so use a webhook created this way.
3. Reject requests without the secret#
Compare the header in constant time and answer 401 when it is missing or wrong. A 401 is not retried.
4. Ignore notifications for other applications#
Check that clientId in the payload is your application's Client ID.
5. Answer quickly, then read the data with your API key#
Answer 2xx within 10 seconds and process afterwards. Treat the payload only as a signal: fetch the Item (or the resource the event names) with your API key and act on what the API returns.
6. Rotate the secret without dropping notifications#
Deploy the new value as WEBHOOK_SECRET and keep the old one as WEBHOOK_SECRET_PREVIOUS. Then update the webhook with PATCH /webhooks/{id} (updateWebhook in the SDK), and remove the old value once the webhook is updated. See Verifying notifications.
Code#
import crypto from 'node:crypto'
import express from 'express'
import { PluggyClient } from 'pluggy-sdk'
const {
PLUGGY_CLIENT_ID,
PLUGGY_CLIENT_SECRET,
WEBHOOK_SECRET,
WEBHOOK_SECRET_PREVIOUS, // set only while rotating
} = process.env
const pluggy = new PluggyClient({
clientId: PLUGGY_CLIENT_ID,
clientSecret: PLUGGY_CLIENT_SECRET,
})
const SECRET_HEADER = 'X-Webhook-Secret'
// 2. Run once, from your server, to register the webhook.
export async function registerWebhook() {
return pluggy.createWebhook('all', 'https://api.example.com/pluggy/webhook', {
[SECRET_HEADER]: WEBHOOK_SECRET,
})
}
// 6. Run after deploying the new WEBHOOK_SECRET, while the old one is still accepted.
export async function rotateWebhookSecret(webhookId) {
return pluggy.updateWebhook(webhookId, {
headers: { [SECRET_HEADER]: WEBHOOK_SECRET },
})
}
// 3. Constant-time comparison, against the current and (while rotating) the previous secret.
function hasValidSecret(received) {
if (typeof received !== 'string') return false
return [WEBHOOK_SECRET, WEBHOOK_SECRET_PREVIOUS]
.filter(Boolean)
.some((secret) => {
const a = Buffer.from(received)
const b = Buffer.from(secret)
return a.length === b.length && crypto.timingSafeEqual(a, b)
})
}
async function handleNotification({ event, itemId }) {
if (event.startsWith('item/') && event !== 'item/deleted') {
// 5. Read the current state with your API key; don't act on the payload.
const item = await pluggy.fetchItem(itemId)
console.log(`Item ${item.id} is ${item.status}`)
}
// Handle the other events you subscribed to the same way.
}
const app = express()
app.post('/pluggy/webhook', express.json(), (req, res) => {
if (!hasValidSecret(req.get(SECRET_HEADER))) {
return res.sendStatus(401)
}
// 4. Only notifications for your application.
if (req.body?.clientId !== PLUGGY_CLIENT_ID) {
console.warn('Ignoring a notification for another clientId')
return res.sendStatus(204)
}
// 5. Answer first, process afterwards.
res.sendStatus(204)
handleNotification(req.body).catch((error) => {
console.error('Could not process notification', req.body.eventId, error.message)
})
})
app.listen(3000)