Paymaster Webhook


Paymaster API reference



If our paymaster service's native restriction policies do not meet your verification requirements, you can use webhook capabilities to relocate the logic for verifying whether to cover gas costs to your own service.

Please follow the steps below to experience our paymaster webhook capabilities.

Fig1. The flow diagram of paymaster webhook

Fig1. The flow diagram of paymaster webhook

1. Create or update policy with webhook configuration

Call the create policy API or update policy API to add webhook configuration.

  "webhook":{ // add this field to update webhook configuration
statusStringThe value should be "active" or "stopped", it decides whether send the verification request to target url.not required, default is "stopped"
urlStringThe URL of webhook target. The maximum length is 128.not required
tokenStringThe identity token of webhook. The maximum length is 256. If the token is provided, the http request will add the header "Authorization", and the format of the value is "Bear "+ token.not required

2. Call zan_requestPaymasterAndData API with webhook data

When the user call the zan_requestPaymasterAndData API to get the paymasterAndData, add parameter webhookData, which contains data required for verification.

For example, if a dapp developer need the user’s identity information for verification, the user's request should look like bellow:

  "id": 1,
  "jsonrpc": "2.0",
  "method": "zan_requestPaymasterAndData",
  "params": {
    "policyId": "12345678-5555-6666-7777-1234567890ab",
    "entryPoint": "0x1234567890123456789012345678901234567890",
    "userOperation": {
      "sender": "0x1234567890123456789012345678901234567890",
      "initCode": "0x1234567890123456789012345678901234567890",
      "callData": "0x1234567890123456789012345678901234567890",
      "nonce": "0x11",
      "callGasLimit": "0x1111",
      "verificationGasLimit": "0x1111",
      "preVerificationGas": "0x1111",
      "maxFeePerGas": "0x1111111111111111111",
      "maxPriorityFeePerGas": "0x1111111111111111111"
    "webhookData": "{\"userIdentity\":\"aaabbbccc\"}"

3. Paymaster webhook process

If the webhook.status is active, the ZAN paymaster service will send a POST request to webhook.url, and make a decision on whether to sponsor the gas depending on the response.

The request body is webhookData. And The expected format of the response body is as follows:

  "isValidationPassed": true