How to turn a webhook into a signed blockchain transaction
Point the webhook at Lit Triggers, verify the sender's signature inside a Lit Action, and sign the transaction with a wallet whose key stays in a secure enclave. Here is how to do it so a forged or repeated webhook cannot move money.
To turn a webhook into a signed blockchain transaction, send the webhook to Lit Triggers, which runs a Lit Action for each delivery. The action checks the sender's signature on the exact bytes it received, then signs and sends the transaction with a Lit wallet whose key stays inside a secure enclave. The webhook secret is decrypted only inside the action, and a contract on the chain rejects any event it has already processed. Your server does not need to hold a key or stay online.
As an example, I will record paid orders on-chain. When your payment system sends an "order paid" webhook, the action calls a contract that records the order.
Why the signature check comes first
The Triggers webhook URL is public, so anyone who finds it can post to it. The action must check that each request really came from your payment system before it signs anything. Providers sign each webhook with a shared secret and put the signature in a header. GitHub signs the raw body with HMAC-SHA256, and Stripe and Slack sign a timestamp plus the body. Triggers passes the raw body to the action as params.event_raw. The only signature headers it passes are x-hub-signature-256, x-hub-signature, stripe-signature, x-slack-signature, x-slack-request-timestamp, x-webhook-signature, and x-signature. Other provider headers are dropped, along with headers that carry secrets. Check that your provider uses one of these before you build on it.
The action
// order-paid.js
const PKP = "0xYourLitWallet...";
const SECRET_CIPHERTEXT = "..."; // webhook secret, encrypted to the wallet
const ORDERS = "0xYourOrdersContract...";
const MAX_AGE_SECONDS = 300;
const safeEqual = (a, b) => {
if (typeof a !== "string" || typeof b !== "string" || a.length !== b.length) return false;
let diff = 0;
for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
return diff === 0;
};
const main = async (params) => {
const secret = await Lit.Actions.Decrypt({ pkpId: PKP, ciphertext: SECRET_CIPHERTEXT });
const raw = params.event_raw || "";
const provided = (params.headers["x-hub-signature-256"] || [])[0];
const expected = "sha256=" + ethers.utils.computeHmac(
ethers.utils.SupportedAlgorithm.sha256, ethers.utils.toUtf8Bytes(secret), ethers.utils.toUtf8Bytes(raw)
).slice(2);
if (!safeEqual(provided, expected)) return { recorded: false, reason: "bad signature" };
const { orderId, amountCents, sentAt } = JSON.parse(raw);
if (Math.abs(Date.now() / 1000 - Number(sentAt)) > MAX_AGE_SECONDS) return { recorded: false, reason: "too old" };
const provider = new ethers.providers.StaticJsonRpcProvider("https://mainnet.base.org");
const wallet = new ethers.Wallet(await Lit.Actions.getPrivateKey({ pkpId: PKP }), provider);
const orders = new ethers.Contract(ORDERS, ["function record(bytes32 orderId, uint256 amountCents)"], wallet);
const tx = await orders.record(ethers.utils.id(String(orderId)), amountCents);
return { recorded: true, hash: tx.hash };
};The action checks the signature before it reads anything else, and it rejects messages older than five minutes. Triggers passes each header as a list of values, so the action takes the first one. It compares the signatures in constant time, so the comparison does not leak how many characters matched. This example uses the GitHub-style x-hub-signature-256 header. If your provider uses stripe-signature or x-slack-signature, build the signed string the way the provider documents, which includes its timestamp.
Stopping repeats
Providers retry webhooks, and an attacker who captures a valid request can send it again within the time window. The action does not remember past runs, so the contract has to. Have record revert when it sees an order ID it already has. Then the transaction for a second delivery of the same webhook reverts, and the order is recorded once.
mapping(bytes32 => bool) public recorded;
function record(bytes32 orderId, uint256 amountCents) external onlyRecorder {
require(!recorded[orderId], "already recorded");
recorded[orderId] = true;
emit OrderRecorded(orderId, amountCents);
}Set the recorder address that onlyRecorder checks to the Lit wallet's address, so only this action can write to the contract.
Set it up
Create an account at the Lit dashboard by clicking Create an account. Then set things up in this order, because pasting the ciphertext into the action changes the action's code hash:
- Create a Lit wallet and a group, and add the wallet to the group.
- Add a small one-off action that calls
Lit.Actions.Encryptto the group, and run it to encrypt the webhook secret to the wallet. - Paste the ciphertext into
order-paid.js, add the final action to the group, and remove the one-off action. - Make a usage key that can only run that group.
The post on sending email without exposing your email provider's API key shows the same sealing step.
Authorize Lit Triggers by following the pairing steps in the Triggers docs, then create the webhook trigger.
jq -n --rawfile code order-paid.js --arg key "$USAGE_KEY" \
'{name: "order-paid", kind: "webhook", action_code: $code, usage_api_key: $key, max_runs_per_minute: 30, max_queued_runs: 100, config: {}}' \
| curl -fsS -X POST https://triggers.litprotocol.com/api/triggers \
-H "authorization: Bearer $TOKEN" -H "content-type: application/json" -d @-Point your payment system at https://triggers.litprotocol.com/webhook/<trigger-id>. Each delivery gets a run ID, and the run history shows what the action returned.
What the setup protects
A forged webhook fails the signature check, a repeated one fails at the contract, and the signing key never leaves the enclave. The rate limits on the trigger cap how many runs the webhook URL can start. The webhook secret matters as much as the key, because anyone who has it can sign valid requests, so keep it only in your payment system and in the sealed ciphertext.
Get started
To create an account, go to the Lit dashboard and click Create an account. Webhook triggers are documented at developer.litprotocol.com/lit-triggers/triggers.