Looking for the previous documentation?Go to v1.docs.pluggy.ai
← Back to Recipes

Authenticate webhook notifications with a header secret

Register your webhook with a secret header, reject requests without it, check the clientId, and read the data with your API key instead of trusting the payload.

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#

javascript
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)