Webhook Security

​

Overview

• The request was sent by Moralis
• The payload was not tampered with
• Your application is protected against spoofed requests

​

How Webhook Signing Works

x-signature

1. Serializing the webhook payload
2. Appending your account’s secret
3. Computing a Keccak-256 hash (via web3.utils.sha3)

signature = sha3(JSON.stringify(body) + secret)

​

What Is the Secret Key?

• It is not your API key
• It is used only for webhook verification
• It can be retrieved via the Streams settings endpoint

​

Verifying Webhook Signatures

1. Read the x-signature header
2. Recompute the signature using the request body and your secret
3. Compare the two values
4. Reject the request if they do not match

​

Example: Node.js (Express)

import { Web3 } from "web3";

function verifySignature(req, secret) {
  const providedSignature = req.headers["x-signature"];
  if (!providedSignature) {
    throw new Error("Missing signature");
  }

  const web3 = new Web3();
  const expectedSignature = web3.utils.sha3(
    JSON.stringify(req.body) + secret
  );

  if (expectedSignature !== providedSignature) {
    throw new Error("Invalid signature");
  }
}

​

Security Best Practices

​

Always verify signatures

• Source IP
• User-Agent headers
• Payload structure alone

​

Use HTTPS

​

Keep handlers lightweight

​

Make handlers idempotent

​

What Happens If Verification Fails?

• Rejects the request (non-2xx)
• Throws an error
• Times out

• The webhook is considered failed
• Automatic retries will occur
• The stream’s success rate may drop

​

Relationship to Other Webhook Concepts