Webhooks

Webhook subscriptions and delivery rules for Portal's public API.

Webhooks allow external systems to receive real-time notifications when specific events occur in Portal.

Developers can register webhook subscriptions by providing an HTTPS endpoint URL and selecting which events they want to receive. When a subscribed event occurs, Portal sends an HTTP POST request to the configured endpoint.

Each request contains a structured JSON payload describing the event.

Webhook deliveries are signed using a secret key to allow consumers to verify that the request was sent by Portal.

If a webhook delivery fails, Portal automatically retries the delivery several times. Current implementation schedule: 1 minute, 5 minutes, 30 minutes, 2 hours, 12 hours.

Security

Webhook requests are signed so consumers can verify that the request was sent by Portal.

Each subscription has a secretKey, which is used to generate a signature for every webhook request.

Signature header

Each webhook request includes the following header:

X-Webhook-Signature

Example:

X-Webhook-Signature: t=1710000000,v1=5f2b3e7a9d1c4f8e6b2a3c9d7f4e1a6b5c3d2f7e9a1b4c6d8e0f2a3b5c7d9e1

Where:

• t - timestamp when the webhook was generated (Unix time)
• v1 - HMAC-SHA256 signature

Signature generation

The signature is calculated using HMAC-SHA256 with the subscription secretKey.

The message being signed is:

timestamp + "." + requestBody

Example:

1710000000.{"id":10025,"number":4123,...}

Signature calculation:

signature = HMAC_SHA256(secretKey, timestamp + "." + requestBody)

Verifying the signature

Consumers should verify webhook requests using the following steps:

1. Read the raw request body exactly as received.
2. Read the X-Webhook-Signature header.
3. Extract t and v1.
4. Rebuild the signed message as t + "." + requestBody.
5. Compute HMAC_SHA256(secretKey, signedMessage).
6. Compare the computed value with v1.
7. Reject the request if the values do not match.
8. Reject the request if the timestamp is too old (recommended tolerance: 5 minutes).