Webhooks

Para webhooks send real-time HTTP POST requests to your server when events occur in your integration — such as a user signing up, a wallet being created, or a transaction being signed. Use webhooks to trigger backend workflows, sync data, or send notifications without polling.

Configure Webhooks

Set up webhooks from your API key’s Webhooks page in the .

Set Your Endpoint URL

Enable the webhook toggle and enter your HTTPS endpoint URL. Para will send POST requests to this URL when subscribed events occur.

Webhook URL configuration in the Developer Portal

Only HTTPS URLs are accepted. HTTP endpoints will be rejected.

Select Events

Choose which events you want to receive. You must select at least one event type when webhooks are enabled.

Webhook event type selection in the Developer Portal

Save and Copy Your Secret

When you first save your webhook configuration, Para generates a signing secret (prefixed with whsec_). This secret is displayed only once — copy and store it securely. You’ll use it to verify webhook signatures.

Webhook secret displayed after initial configuration

Your webhook secret is shown only at creation and after rotation. If you lose it, you’ll need to rotate to get a new one.

Test Your Endpoint

Click Test Webhook to send a test.ping event to your endpoint. This verifies connectivity without triggering a real event.

Event Types

Event	Description
`user.created`	A new user was created
`wallet.created`	A new wallet was created for a user
`transaction.signed`	A transaction was signed
`send.broadcasted`	A Para Send transaction was broadcasted to the network
`send.confirmed`	A Para Send transaction was confirmed on-chain
`send.failed`	A Para Send transaction failed
`rest.transaction.confirmed`	A REST API v1 broadcast transaction was confirmed on-chain
`rest.transaction.failed`	A REST broadcast reverted, was superseded by an identified same-nonce transaction, or failed during signing/broadcast
`wallet.pregen_claimed`	A pre-generated wallet was claimed by a user
`user.external_wallet_verified`	A user verified an external wallet
`onramp.completed`	A fiat on-ramp purchase settled on-chain

Event Payload

Every webhook request contains a JSON body with a standard envelope wrapping the event-specific data:

{
  "id": "evt_550e8400-e29b-41d4-a716-446655440000",
  "type": "user.created",
  "createdAt": "2026-02-07T12:00:00.000Z",
  "data": {
    // event-specific fields
  }
}

Field	Description
`id`	Unique event ID prefixed with `evt_`
`type`	The event type string
`createdAt`	ISO 8601 timestamp of when the event was created
`data`	Event-specific payload (see below)

Event Data by Type

user.created

{
  "userId": "d5358219-38d3-4650-91a8-e338131d1c5e",
  "userCreatedAt": "2026-02-07T12:00:00.000Z"
}

wallet.created

{
  "userId": "d5358219-38d3-4650-91a8-e338131d1c5e",
  "walletId": "de4034f1-6b0f-4a98-87a5-e459db4d3a03",
  "walletAddress": "0x9dd3824f045c77bc369485e8f1dd6b452b6be617",
  "walletType": "EVM",
  "walletCreatedAt": "2026-02-07T12:00:00.000Z"
}

transaction.signed

{
  "userId": "d5358219-38d3-4650-91a8-e338131d1c5e",
  "walletId": "de4034f1-6b0f-4a98-87a5-e459db4d3a03",
  "walletAddress": "0x9dd3824f045c77bc369485e8f1dd6b452b6be617",
  "chainId": 1,
  "signedAt": "2026-02-07T12:00:00.000Z"
}

The chainId field is null for message signing operations where no chain is involved.

send.broadcasted

{
  "userId": "d5358219-38d3-4650-91a8-e338131d1c5e",
  "walletId": "de4034f1-6b0f-4a98-87a5-e459db4d3a03",
  "txHash": "0xabc123...",
  "type": "EVM",
  "evmChainId": "1",
  "isDevnet": false,
  "broadcastedAt": "2026-02-07T12:00:00.000Z"
}

For Solana transactions, type will be "SOLANA" and evmChainId will be absent. isDevnet indicates if the transaction was on a devnet.

send.confirmed

{
  "userId": "d5358219-38d3-4650-91a8-e338131d1c5e",
  "walletId": "de4034f1-6b0f-4a98-87a5-e459db4d3a03",
  "txHash": "0xabc123...",
  "type": "EVM",
  "evmChainId": "1",
  "isDevnet": false,
  "confirmedAt": "2026-02-07T12:00:00.000Z"
}

send.failed

{
  "userId": "d5358219-38d3-4650-91a8-e338131d1c5e",
  "walletId": "de4034f1-6b0f-4a98-87a5-e459db4d3a03",
  "txHash": "0xabc123...",
  "type": "EVM",
  "evmChainId": "1",
  "isDevnet": false,
  "error": "insufficient funds",
  "failedAt": "2026-02-07T12:00:00.000Z"
}

The error field is optional and may be absent if no error message was available.

rest.transaction.confirmed

{
  "transactionId": "550e8400-e29b-41d4-a716-446655440000",
  "walletId": "de4034f1-6b0f-4a98-87a5-e459db4d3a03",
  "partnerId": "11111111-2222-3333-4444-555555555555",
  "intentKind": "transfer",
  "type": "EVM",
  "hash": "0x1234abcd...",
  "blockNumber": "5127103",
  "blockHash": "0xdeadbeef...",
  "resolvedAt": "2026-02-07T12:00:00.000Z"
}

transactionId matches the id returned from POST /v1/wallets/:walletId/transfer or POST /v1/wallets/:walletId/sign-transaction with broadcast: true and used by GET /v1/wallets/:walletId/transactions/:transactionId. intentKind is transfer, sign_transaction, or yield. For yield, each event describes one approval or Aave transaction; check the yield operation for the overall result. Legacy EVM transfer and signing broadcasts resolve only after canonical receipt and finalized-block checks. Solana broadcasts require finalized signature status. A confirmation may arrive after the active monitoring window ends.

rest.transaction.failed

{
  "transactionId": "550e8400-e29b-41d4-a716-446655440000",
  "walletId": "de4034f1-6b0f-4a98-87a5-e459db4d3a03",
  "partnerId": "11111111-2222-3333-4444-555555555555",
  "intentKind": "transfer",
  "type": "EVM",
  "status": "reverted",
  "hash": "0x1234abcd...",
  "failureMessage": "execution reverted",
  "resolvedAt": "2026-02-07T12:00:00.000Z"
}

status is reverted (verified execution failure on-chain) or failed (signing/broadcast failure or an identified same-nonce winner). failureStage identifies signing/broadcast failures; failureCode may be REPLACED or CANCELLED for a superseded original transaction. Reconciliation payloads may include chainOutcome (success, revert, replacement, or cancellation), winningHash, and winningStatus (confirmed or reverted). The payload’s hash remains the original transaction hash.Active monitoring timeout alone emits no failed event. A broadcast RPC timeout can still emit failed; reconcile the original transaction before retrying a payment, as described in Failure Fields. Older monitor_timeout events do not prove chain failure; fetch the current transaction record before applying a delayed event. Delivery is at least once; deduplicate retries using the stable webhook-id header.

wallet.pregen_claimed

{
  "userId": "d5358219-38d3-4650-91a8-e338131d1c5e",
  "walletId": "de4034f1-6b0f-4a98-87a5-e459db4d3a03",
  "walletAddress": "0x9dd3824f045c77bc369485e8f1dd6b452b6be617",
  "walletType": "EVM",
  "claimedAt": "2026-02-07T12:00:00.000Z"
}

user.external_wallet_verified

{
  "userId": "d5358219-38d3-4650-91a8-e338131d1c5e",
  "walletAddress": "0xaD6b78193b78e23F9aBBB675734f4a2B3559598D",
  "walletProvider": "MetaMask",
  "verifiedAt": "2026-02-07T12:00:00.000Z"
}

The walletProvider field is optional and may be absent depending on how the wallet was connected.

onramp.completed

{
  "userId": "d5358219-38d3-4650-91a8-e338131d1c5e",
  "purchaseId": "9f2c61d4-7ab8-4c03-b5e1-2d8f4a6c9017",
  "provider": "COINBASE",
  "paymentMethod": "APPLE_PAY",
  "transactionHash": "0x1234abcd...",
  "asset": {
    "symbol": "USDC",
    "name": "USD Coin",
    "contractAddress": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
    "type": "EVM",
    "chainId": "8453",
    "networkName": "Base",
    "decimals": 6
  },
  "assetQuantity": "25.00",
  "fiatAmount": "25.00",
  "fiatCurrency": "USD",
  "walletId": "de4034f1-6b0f-4a98-87a5-e459db4d3a03",
  "destinationAddress": "0x9dd3824f045c77bc369485e8f1dd6b452b6be617",
  "testMode": false,
  "completedAt": "2026-02-07T12:00:00.000Z"
}

Fired once the fulfilling provider confirms the crypto was delivered — supported for Coinbase (both the hosted widget and inline Apple Pay), MoonPay, Ramp, and Stripe. purchaseId is the same id the SDK reports on the ONRAMP_LAUNCHED event, so you can correlate the event with the launch.transactionHash is null when the provider settled without reporting an on-chain hash. walletId is absent when the destination was a raw external address rather than a Para wallet. The asset fields are best-effort — an empty object means the delivered token could not be resolved against the catalog.Check testMode before recording the purchase in production accounting: test purchases run a real quote but are never charged, and they emit this event exactly like live ones.

TypeScript Types

If your handler is written in TypeScript, @getpara/rest-sdk (3.20+) exports types for every event above, so you don’t have to restate those shapes by hand. Use ParaWebhookEvent rather than the generic WebhookEvent — it’s a discriminated union, so a switch on event.type narrows event.data to that event’s payload:

import { WebhookEventType, type ParaWebhookEvent } from "@getpara/rest-sdk";

export function handleParaWebhook(event: ParaWebhookEvent) {
  switch (event.type) {
    case WebhookEventType.WALLET_CREATED:
      // event.data is WalletCreatedPayload
      return index(event.data.walletAddress);
    case WebhookEventType.ONRAMP_COMPLETED:
      // event.data is OnrampCompletedPayload
      return credit(event.data.purchaseId, event.data.transactionHash);
  }
}

The individual payload interfaces (WalletCreatedPayload, OnrampCompletedPayload, …) and ParaWebhookPayload<K> are exported too, for typing a single-event handler. These are types only — verifying the signature is still your handler’s job, as described below.

Verify Webhook Signatures

Every webhook request includes headers that let you verify the request came from Para:

Header	Description
`webhook-id`	Unique event ID (matches payload `id`)
`webhook-timestamp`	Unix timestamp in seconds when the request was sent
`webhook-signature`	HMAC-SHA256 signature prefixed with `v1,`

To verify a webhook:

Construct the signed message: {webhook-timestamp}.{raw request body}
Compute HMAC-SHA256 using your webhook secret as the key
Base64-encode the result and compare it to the signature after the v1, prefix

import crypto from "crypto";

function verifyWebhookSignature(
  payload: string,
  headers: Record<string, string>,
  secret: string
): boolean {
  const timestamp = headers["webhook-timestamp"];
  const signature = headers["webhook-signature"];

  if (!timestamp || !signature) return false;

  // Reject requests older than 5 minutes
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - parseInt(timestamp)) > 300) return false;

  const message = `${timestamp}.${payload}`;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(message)
    .digest("base64");

  // During secret rotation, multiple signatures may be
  // space-delimited (one per active secret). Try each.
  const signatures = signature.split(" ");
  return signatures.some((sig) => {
    const received = sig.replace("v1,", "");
    return crypto.timingSafeEqual(
      Buffer.from(expected),
      Buffer.from(received)
    );
  });
}

// Usage in an Express handler
app.post("/webhook", (req, res) => {
  const rawBody = req.body; // use raw body string, not parsed JSON
  const isValid = verifyWebhookSignature(
    rawBody,
    req.headers,
    process.env.WEBHOOK_SECRET
  );

  if (!isValid) {
    return res.status(401).send("Invalid signature");
  }

  const event = JSON.parse(rawBody);

  switch (event.type) {
    case "user.created":
      // handle user creation
      break;
    case "wallet.created":
      // handle wallet creation
      break;
    // ...
  }

  res.status(200).send("OK");
});

import hmac
import hashlib
import base64
import time
import json

def verify_webhook_signature(payload: str, headers: dict, secret: str) -> bool:
    timestamp = headers.get("webhook-timestamp", "")
    signature = headers.get("webhook-signature", "")

    if not timestamp or not signature:
        return False

    # Reject requests older than 5 minutes
    if abs(time.time() - int(timestamp)) > 300:
        return False

    message = f"{timestamp}.{payload}"
    expected = base64.b64encode(
        hmac.new(secret.encode(), message.encode(), hashlib.sha256).digest()
    ).decode()

    # During secret rotation, multiple signatures may be
    # space-delimited (one per active secret). Try each.
    signatures = signature.split(" ")
    return any(
        hmac.compare_digest(expected, sig.replace("v1,", ""))
        for sig in signatures
    )

# Usage in a Flask handler
@app.route("/webhook", methods=["POST"])
def webhook():
    raw_body = request.get_data(as_text=True)
    is_valid = verify_webhook_signature(
        raw_body,
        request.headers,
        os.environ["WEBHOOK_SECRET"],
    )

    if not is_valid:
        return "Invalid signature", 401

    event = json.loads(raw_body)

    if event["type"] == "user.created":
        pass  # handle user creation
    elif event["type"] == "wallet.created":
        pass  # handle wallet creation

    return "OK", 200

Always use the raw request body string for verification — not a re-serialized JSON object. Re-serialization can change formatting and break the signature check.

Manage Your Webhook

Rotate Secret

If your secret is compromised or you need a new one, rotate it from the Danger Zone section of the Webhooks page. The previous secret remains valid for 24 hours to give you time to update your server. A new secret is displayed once.

Webhook danger zone with rotate and delete options

Disable or Delete

Toggle webhooks off to temporarily stop delivery without losing your configuration. To remove the webhook entirely, use the Delete Webhook button — this removes the URL, events, and secret permanently.

Best Practices

Respond quickly: Return a 2xx status within a few seconds. Offload heavy processing to a background job.
Verify signatures: Always validate the webhook-signature header before trusting the payload.
Check timestamps: Reject webhooks with timestamps more than 5 minutes old to prevent replay attacks.
Handle duplicates: Use the webhook-id header to deduplicate events in case of retries.
Use HTTPS: Your endpoint must be HTTPS. Para rejects HTTP URLs.

Getting Started

Choose a Path

Project Setup

Go Live

How Para Works

Shared Guides

Migrations

Configure Webhooks

Set Your Endpoint URL

Select Events

Save and Copy Your Secret

Test Your Endpoint

Event Types

Event Payload

Event Data by Type

TypeScript Types

Verify Webhook Signatures

Manage Your Webhook

Rotate Secret

Disable or Delete

Best Practices

​Configure Webhooks

​Set Your Endpoint URL

​Select Events

​Save and Copy Your Secret

​Test Your Endpoint

​Event Types

​Event Payload

​Event Data by Type

​TypeScript Types

​Verify Webhook Signatures

​Manage Your Webhook

​Rotate Secret

​Disable or Delete

​Best Practices

Configure Webhooks

Set Your Endpoint URL

Select Events

Save and Copy Your Secret

Test Your Endpoint

Event Types

Event Payload

Event Data by Type

TypeScript Types

Verify Webhook Signatures

Manage Your Webhook

Rotate Secret

Disable or Delete

Best Practices