Webhook Security Measures

Securing Calls to Destination

When creating or updating a webhook, you can configure authentication that Propelus will use when sending requests to your endpoint. This ensures that only authorized requests from Propelus are accepted by your server.

Configuration Schema

{
"authentication": {
"method": "apiKey" | "bearer" | "basic",
"value": "<your-authentication-value>"
}
}

How It Works

When you configure authentication with method: “apiKey”, Propelus includes your configured value in every webhook request as an HTTP header:

x-api-key: <value_defined_in_creation>

cURL Example: Creating a Webhook with API Key Authentication

Request:
curl -X POST "https://api.propelus.com/v2/webhooks" \
-H "Content-Type: application/json" \
-H "x-api-key: <YOUR_PROPELUS_API_KEY>" \
-H "x-client-id: <YOUR_CLIENT_ID>" \
-d '{
"eventType": "credentialVerified",
"url": "https://your-server.com/webhooks/propelus",
"authentication": {
"method": "apiKey",
"value": "your-secret-webhook-api-key-12345"
}
}'

Resulting Webhook Request to Your Server:

POST /webhooks/propelus HTTP/1.1
Host: your-server.com
Content-Type: application/json
x-api-key: your-secret-webhook-api-key-12345
 
{ ... event payload ... }

Server-Side Validation Example

// Express.js middleware example
function validateWebhookAuth(req, res, next) {
const apiKey = req.headers['x-api-key'];
const expectedKey = process.env.PROPELUS_WEBHOOK_API_KEY;
 
if (!apiKey || apiKey !== expectedKey) {
return res.status(401).json({ error: 'Unauthorized' });
}
next();
}
 
app.post('/webhooks/propelus', validateWebhookAuth, (req, res) => {
// Process webhook event
});

Signature Verification

For enhanced security, you can configure webhook signature verification. Propelus will sign each webhook payload using HMAC-SHA256, allowing you to verify that requests genuinely originated from Propelus and haven't been tampered with.

Configuration Schema

{
"signature": {
"key": "<your-secret-signing-key>"
}
}

How It Works

When signature verification is configured, Propelus includes a signature header in every webhook request:

x-propelus-signature: <computed_signature>

The signature is computed using the following formula:

const signatureValue = crypto.createHmac('sha256', signature.key)
.update(`${requestBody}.${clientId}`)
.digest('base64');

Where:

• signature.key = The secret key you configured when creating the webhook
• requestBody  = The raw JSON body of the webhook request (as a string)
• clientId = Your Propelus client ID

Example: Creating a Webhook with Signature Verification

Request:

curl -X POST "https://api.propelus.com/v2/webhooks" \
-H "Content-Type: application/json" \
-H "x-api-key: <YOUR_PROPELUS_API_KEY>" \
-H "x-client-id: <YOUR_CLIENT_ID>" \
-d '{
"eventType": "credentialVerified",
"url": "https://your-server.com/webhooks/propelus",
"signature": {
"key": "a3f8c92e5d1b4f7a9e6c2d8b3f5a1c4e"
}
}'

Server-Side Signature Verification Example

const crypto = require('crypto');
 
function verifyWebhookSignature(req, res, next) {
const signature = req.headers['x-propelus-signature'];
const secretKey = process.env.PROPELUS_WEBHOOK_SECRET;
const clientId = process.env.PROPELUS_CLIENT_ID;
 
// Get raw body as string
const rawBody = JSON.stringify(req.body);
 
// Compute expected signature
const expectedSignature = crypto
.createHmac('sha256', secretKey)
.update(`${rawBody}.${clientId}`)
.digest('base64');
 
if (!signature || signature !== expectedSignature) {
return res.status(401).json({ error: 'Invalid signature' });
}
next();
}
 
app.post('/webhooks/propelus',
express.json({ verify: (req, res, buf) => { req.rawBody = buf.toString(); }}),
verifyWebhookSignature,
(req, res) => {
// Process webhook event
}
);

Combined Authentication and Signature
You can use both authentication and signature verification together for maximum security:

{
  "eventType": "credentialVerified",
  "url": "https://your-server.com/webhooks/propelus",
  "authentication": {
    "method": "apiKey",
    "value": "your-secret-api-key"
  },
  "signature": {
    "key": "your-hmac-signing-key"
  }
}

Webhook Endpoints

(!) All webhook endpoints require header authentication using your Propelus API credentials:

• x-api-key: Your API key
• x-client-id: Your client ID

Where to go next

Webhooks - Creation, Registration & Activation