Skip to main content
Swagger
All documentation pages

Webhook Request and Response

Use this information to build the webhook that Portal calls.

Request

Portal sends a POST request with a JSON body that contains the member’s email address:

POST <your webhook URL>
Content-Type: application/json
Portal-Signature: t=1767225600,v0=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

{"email":"jane@example.com"}
  • Portal can add properties to the JSON request body in future releases. Your webhook must ignore properties that it doesn’t recognize.
  • Portal enforces a three-second response timeout.
  • Portal doesn’t retry a failed request.

Verify the Signature

Verify Portal-Signature before you issue a token, and reject requests that fail. Without verification, anyone who learns your webhook URL can request tokens for any email address. To verify a request:

  1. Read the timestamp t and the signature v0 from the Portal-Signature header.
  2. Reject the request if the timestamp is more than 300 seconds from your server clock.
  3. Read the raw request body exactly as you received it. Don’t parse and re-serialize the JSON.
  4. Compute an HMAC-SHA256 hash of <t>.<raw body> with your signing secret, and encode it as hex.
  5. Compare your result with v0 by using a constant-time comparison.

The following Node.js (Express) example verifies the signature and returns a token. The isValidSignature function uses only the Node crypto module, so you can copy it into your own service as is.

import { createHmac, timingSafeEqual } from 'node:crypto'
import express from 'express'

const SECRET = process.env.PORTAL_WEBHOOK_SECRET!
const TOLERANCE_SECONDS = 300

const isValidSignature = (header: string | undefined, rawBody: string): boolean => {
  const parts = header?.split(',') ?? []
  if (parts.length !== 2 || !parts[0].startsWith('t=') || !parts[1].startsWith('v0=')) { return false }

  const timestamp = parts[0].slice(2)
  const signature = parts[1].slice(3)
  if (!/^\d{1,15}$/.test(timestamp) || !/^[0-9a-f]{64}$/.test(signature)) { return false }

  const age = Math.floor(Date.now() / 1000) - Number(timestamp)
  if (Math.abs(age) > TOLERANCE_SECONDS) { return false }

  const expected = createHmac('sha256', SECRET).update(`${timestamp}.${rawBody}`).digest()
  const actual = Buffer.from(signature, 'hex')
  return expected.length === actual.length && timingSafeEqual(expected, actual)
}

const app = express()

// Keep the body as a raw string so the signature is checked against the exact bytes received
app.post('/portal-token', express.text({ type: 'application/json' }), async (req, res) => {
  if (!isValidSignature(req.get('Portal-Signature'), req.body)) {
    res.status(401).end()
    return
  }

  const { email } = JSON.parse(req.body)
  const token = await issueTokenFor(email) // your logic

  res.json({ token, audience: ['https://api.example.com'] })
})

Response

Respond with a 2xx status, a Content-Type that includes application/json, and a JSON object of 64 KB or less:

{
  "token": "eyJhbGciOi...",
  "audience": ["https://api.example.com"]
}
Property Required Description
token Yes A non-empty string. Portal sends it as Authorization: Bearer <token>. Bearer is the only supported authentication scheme.
audience No An array of HTTPS origins that can receive the token, in addition to the origin of your webhook URL. Required if your API runs on a different host than your webhook. Otherwise, Portal doesn’t add the token, and requests to the API return 401. Each origin must be an exact HTTPS origin of 2048 characters or fewer, with no path, query, fragment, or credentials, for example https://api.example.com:8443. Portal normalizes each origin: it converts the host to lowercase and drops a trailing slash and the default port 443. Portal examines only the first 100 entries, drops invalid entries, collapses duplicates, and keeps no more than 10 valid origins. The origin of your webhook URL doesn’t count toward the 10.
  • To issue no token for a member, return a non-2xx status.
  • Portal ignores unknown properties.

Do not include sensitive data beyond the token in the response, and avoid logging tokens or email addresses.

Was this page helpful?