Docs

Webhooks

Configure webhooks in Engine to notify your backend server of transaction or backend wallet events.

Supported events

Transactions

EventDescription
queued_transactionA transaction is added to the Engine queue.
sent_transactionA transaction is submitted to an RPC provider. A transaction hash is provided, but it may not be mined onchain yet.
mined_transactionA transaction is mined on the blockchain. A transaction hash is provided, and it is mined onchain.
errored_transactionA transaction is unable to be submitted. There may be an error in the transaction params, backend wallet, or server.
all_transactionAll the above events. The status field will be one of: queued, sent, mined, errored.
Webhooks lifecycle

Wallets

EventDescription
backend_wallet_balanceA backend wallet's balance is below minWalletBalance. To read or update this value, call GET/POST /configuration/backend-wallet-balance.

Setup

Create a webhook

  • Visit the Engine dashboard.
  • Select the Configuration tab.
  • Select Create Webhook.

Webhook URLs must start with https://.

Since any outside origin can call your webhook endpoint, it is recommended to verify the webhook signature to ensure a request comes from your Engine instance.

Check the signature

The payload body is signed with the webhook secret and provided in the X-Engine-Signature request header.

Get the webhook secret for your webhook endpoint from the dashboard.

This code example checks if the signature is valid:

const generateSignature = (
  body: string,
  timestamp: string,
  secret: string,
): string => {
  const payload = `${timestamp}.${body}`;
  return crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
};
 
const isValidSignature = (
  body: string,
  timestamp: string,
  signature: string,
  secret: string,
): boolean => {
  const expectedSignature = generateSignature(
    body,
    timestamp,
    secret,
  );
  return crypto.timingSafeEqual(
    Buffer.from(expectedSignature),
    Buffer.from(signature),
  );
};

Check the timestamp

The event timestamp is provided in the X-Engine-Timestamp request header.

This code example checks if the event exceeds a given expiration duration:

export const isExpired = (
  timestamp: string,
  expirationInSeconds: number,
): boolean => {
  const currentTime = Math.floor(Date.now() / 1000);
  return currentTime - parseInt(timestamp) > expirationInSeconds;
};

Example webhook endpoint

This NodeJS code example listens for event notifications on the /webhook endpoint:

import express from "express";
import bodyParser from "body-parser";
import { isValidSignature, isExpired } from "./webhookHelper";
 
const app = express();
const port = 3000;
 
const WEBHOOK_SECRET = "<your_webhook_auth_secret>";
 
app.use(bodyParser.text());
 
app.post("/webhook", (req, res) => {
  const signatureFromHeader = req.header("X-Engine-Signature");
  const timestampFromHeader = req.header("X-Engine-Timestamp");
 
  if (!signatureFromHeader || !timestampFromHeader) {
    return res
      .status(401)
      .send("Missing signature or timestamp header");
  }
 
  if (
    !isValidSignature(
      req.body,
      timestampFromHeader,
      signatureFromHeader,
      WEBHOOK_SECRET,
    )
  ) {
    return res.status(401).send("Invalid signature");
  }
 
  if (isExpired(timestampFromHeader, 300)) {
    // Assuming expiration time is 5 minutes (300 seconds)
    return res.status(401).send("Request has expired");
  }
 
  // Process the request
  res.status(200).send("Webhook received!");
});
 
app.listen(port, () => {
  console.log(`Server started on http://localhost:${port}`);
});

Payload format

The webhook request to your backend follows this format.

Method: POST

Headers:

  • Content-Type: application/json
  • X-Engine-Signature: <payload signature>
  • X-Engine-Timestamp: <Unix timestamp in seconds>
{
	"chainId": 80001,
	"data": "0xa9059cbb0000000000000000000000003ecdbf3b911d0e9052b64850693888b008e183730000000000000000000000000000000000000000000000000000000000000064",
	"value": "0x00",
	"gasLimit": "39580",
	"nonce": 1786,
	"maxFeePerGas": "2063100466",
	"maxPriorityFeePerGas": "1875545856",
	"fromAddress": "0x3ecdbf3b911d0e9052b64850693888b008e18373",
	"toAddress": "0x365b83d67d5539c6583b9c0266a548926bf216f4",
	"gasPrice": "1875545871",
	"transactionType": 2,
	"transactionHash": "0xc3ffa42dd4734b017d483e1158a2e936c8a97dd1aa4e4ce11df80ac8e81d2c7e",
	"signerAddress": null,
	"accountAddress": null,
	"target": null,
	"sender": null,
	"initCode": null,
	"callData": null,
	"callGasLimit": null,
	"verificationGasLimit": null,
	"preVerificationGas": null,
	"paymasterAndData": null,
	"userOpHash": null,
	"functionName": "transfer",
	"functionArgs": "0x3ecdbf3b911d0e9052b64850693888b008e18373,100",
	"extension": "none",
	"deployedContractAddress": null,
	"deployedContractType": null,
	"queuedAt": "2023-09-29T22:01:31.031Z",
	"processedAt": "2023-09-29T22:01:38.754Z",
	"sentAt": "2023-09-29T22:01:41.580Z",
	"minedAt": "2023-09-29T22:01:44.000Z",
	"cancelledAt": null,
	"retryCount": 0,
	"retryGasValues": false,
	"retryMaxPriorityFeePerGas": null,
	"retryMaxFeePerGas": null,
	"errorMessage": null,
	"sentAtBlockNumber": 40660021,
	"blockNumber": 40660026,
	"queueId": "1411246e-b1c8-4f5d-9a25-8c1f40b54e55",
	"status": "mined"
}