Account Abstraction Webhook

Why Use a Webhook?

User operations in Xellar's Account Abstraction system are asynchronous. This means that after you initiate an operation (such as a transaction or signature request), the result is not immediately available. Instead, the operation progresses through several states until it reaches a final outcome.

To keep your application updated in real time, Xellar provides a webhook mechanism. This allows your backend to receive notifications about important lifecycle events for user operations, so you can update your UI, trigger business logic, or notify users as soon as the status changes.

🔄

Webhooks are essential for tracking the status of user operations without polling the API.

User Operation Lifecycle Events

The following diagram illustrates the lifecycle of a user operation. Orange-highlighted states are the events that will trigger a webhook notification:

User Operation Lifecycle

expired: No signature was submitted before the time limit (validUntil).
success: The user operation was processed successfully.
failed: The user operation failed during processing or after signature submission.

You will receive a webhook event when the user operation reaches any of these states.

How to Set Up the Webhook

You can configure your webhook endpoint in the Xellar Dashboard.

⚠️

Ensure your webhook endpoint is publicly accessible and can handle POST requests.

Webhook Event Data

When a user operation reaches a terminal state (expired, success, or failed), Xellar will send a POST request to your configured webhook URL with the following JSON payload:

{
  "accountId": "68027beb6a1ae347d38563d7",
  "ownerId": "0x123...abc",
  "clientId": "client-xyz",
  "appId": "app-abc",
  "signature": null,
  "userOpHash": "0xabc...def",
  "status": "success",
  "type": "transfer_erc20",
  "network": "polygon",
  "chainId": 137,
  "payer": "organization",
  "validUntil": "2024-06-01T12:00:00Z",
  "failedReason": null,
  "bundlerVersion": "1.2.3",
  "successAt": "2024-06-01T12:01:00Z",
  "failedAt": null,
  "sentAt": "2024-06-01T12:00:10Z"
}

Field	Type	Description
`accountId`	string	The ID of the smart account involved.
`ownerId`	string or object	The owner identifier (may be a string or object depending on context).
`clientId`	string	The client ID associated with the operation.
`appId`	string	The app ID associated with the operation.
`signature`	string or null	The signature submitted for the operation, if any.
`userOpHash`	string	The unique hash of the user operation.
`status`	string	The status of the user operation (`success`, `failed`, `expired`).
`type`	string	The type of user operation (e.g., `transfer_erc20`).
`network`	string	The network name (e.g., `polygon`).
`chainId`	integer	The blockchain network identifier.
`payer`	string	Who paid for the operation (e.g., `organization`, `owner`).
`validUntil`	string (ISO 8601)	The time until which the operation is valid.
`failedReason`	string or null	The reason for failure, if any.
`bundlerVersion`	string	The version of the bundler that processed the operation.
`successAt`	string or null (ISO 8601)	The timestamp when the operation succeeded.
`failedAt`	string or null (ISO 8601)	The timestamp when the operation failed.
`sentAt`	string or null (ISO 8601)	The timestamp when the operation was sent.

ℹ️

Fields such as Data and Receipt are not included in the webhook payload.

ℹ️

Always verify the authenticity of incoming webhook requests and handle them idempotently.

Fee Environment