Webhooks

To receive events instead of polling, open your organization settings in the dashboard and go to the Webhooks tab. Configure the webhook URL and signing secret for that organization.

Delivery format

Events arrive as a JSON POST to your webhook URL:

{
  "event": "<event-name>",
  "token": "<signed-jwt>",
  "data": { }
}

The token is an HS256-signed JWT whose payload is { event, data, iat, exp }, signed with your organization’s webhook secret. The outer event and data fields are unauthenticated convenience copies — always verify the token before trusting anything.

Verifying deliveries

Use resolvePviumWebhookPayload to verify the signed token in a webhook request body and return the verified event and data. If you have already extracted the token, pass it directly to verifyPviumWebhookToken. Each SDK provides both helpers.

import { resolvePviumWebhookPayload } from '@pvium/sdk';

app.post('/webhooks/pvium', (req, res) => {
  try {
    const webhook = resolvePviumWebhookPayload(
      req.body,
      process.env.PVIUM_WEBHOOK_SECRET!,
    );

    handleEvent(webhook.event, webhook.data);
    res.sendStatus(200);
  } catch {
    res.sendStatus(401); // invalid signature — do not process
  }
});

from pvium_sdk import resolvePviumWebhookPayload

@app.post("/webhooks/pvium")
def pvium_webhook():
    try:
        webhook = resolvePviumWebhookPayload(
            request.json,
            os.environ["PVIUM_WEBHOOK_SECRET"],
        )
    except Exception:
        return "", 401  # invalid signature — do not process

    handle_event(webhook["event"], webhook["data"])
    return "", 200

import "github.com/pvium/sdks/go-sdk/webhooks"

func pviumWebhook(w http.ResponseWriter, r *http.Request) {
    var body map[string]any
    if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
        w.WriteHeader(http.StatusBadRequest)
        return
    }

    payload, err := webhooks.ResolvePviumWebhookPayload(
        body,
        os.Getenv("PVIUM_WEBHOOK_SECRET"),
    )
    if err != nil {
        w.WriteHeader(http.StatusUnauthorized) // invalid signature — do not process
        return
    }

    handleEvent(payload.Event, payload.Data)
    w.WriteHeader(http.StatusOK)
}

Verification checks the signature, rejects expired tokens, and checks the event name when an expected event is supplied. A valid token can be delivered more than once; use the deduplication guidance below to avoid processing the same event twice.

Events

All payloads carry appId — your organization’s ID.

Event	Fires when
`batch.payee.added`	A payee is attached to a batch — by direct add, or when an invitee accepts
`batch.funded`	On-chain funding lands for a batch
`batch.payee.claimed`	A recipient claims their payment from a funded batch
`oauth.invite.accepted`	An invited identity completes OAuth and its authorization is active immediately
`oauth.authorization.activated`	A previously pending invite authorization becomes active after required onboarding checks complete
`contract.created`	A contract (such as an invoice) is created against your organization
`payment.attached`	A transfer is attached to a contract installment

Payloads

batch.payee.added

The event can follow either invite acceptance or a direct addition to a batch. Your handler must accept both payload variants; for example, do not require invite details for a payee added directly.

{
  "appId": "65f...",
  "batch": { "id": "uuid-batch", "chain": "base", "status": "pending" },
  "payee": {
    "identityType": "email",
    "identityValue": "alice@example.com",
    "receiver": "0xRecipient...",
    "amount": 100,
    "memo": "Bonus payment"
  },
  "user": { "id": "67d...", "handle": "alice", "email": "alice@example.com" },
  "invite": { "id": "inv-id", "batchId": "uuid-batch", "acceptedAt": "2026-05-12T..." }
}

batch.funded

Instant batches fire once, on the single payment transaction. Scheduled and pool batches fire on every funding transaction — watch batch.fullyFunded for the transition into fully funded.

{
  "appId": "65f...",
  "batch": {
    "id": "uuid-batch",
    "chain": "base",
    "status": "funded",
    "batchHash": "0x...",
    "batchTransactionHash": "0x...",
    "totalFunded": 1500,
    "fullyFunded": true
  },
  "funding": {
    "amount": 1500,
    "token": "0xTokenContract...",
    "fundedAt": 1747068664,
    "transactionHash": "0x..."
  }
}

batch.payee.claimed

Fires the first time a payment transitions from unclaimed to claimed — duplicate claim events are debounced.

{
  "appId": "65f...",
  "batch": { "id": "uuid-batch", "chain": "base", "status": "funded", "batchHash": "0x..." },
  "payee": {
    "paymentId": "uuid-payment",
    "receiver": "0xRecipient...",
    "amount": 250,
    "token": "0xTokenContract...",
    "decimals": 6,
    "memo": "INV-1042:install-3",
    "claimDate": 1747068664
  },
  "claim": {
    "claimedAt": "2026-05-12T18:31:04.000Z",
    "transactionHash": "0xclaim...",
    "onchainAmount": "250000000"
  }
}

oauth.invite.accepted

Delivers the payee’s resolved identity plus the active authorization your organization was granted, including access and refresh tokens. This event is emitted when the authorization is active immediately. If payee screening is pending, handle oauth.authorization.activated instead.

{
  "appId": "65f...",
  "clientId": "app_abcd1234",
  "user": { "id": "67d...", "handle": "alice", "email": "alice@example.com" },
  "authorization": {
    "id": "aa1...",
    "scopes": ["read:user", "read:kyc"],
    "expiresAt": "2027-05-12T18:31:04.000Z",
    "tokenType": "Bearer"
  },
  "accessToken": "access_...",
  "refreshToken": "refresh_...",
  "invite": {
    "identityType": "email",
    "identityValue": "alice@example.com",
    "batchId": "uuid-or-null",
    "acceptedAt": "2026-05-12T18:31:04.000Z"
  }
}

oauth.authorization.activated

Sent when an invite authorization that was pending payee screening becomes active. The authorization is active only after the required onboarding checks for the invite scopes have completed. This event does not prove that the user is payable in a particular batch; use the batch-scoped isPayable check before adding or finalizing a Strict batch.

{
  "appId": "65f...",
  "clientId": "app_abcd1234",
  "user": { "id": "67d...", "handle": "alice", "email": "alice@example.com" },
  "authorization": {
    "id": "aa1...",
    "isActive": true,
    "status": "active",
    "scopes": ["read:user", "read:legal_id", "read:tax_forms"],
    "activatedAt": "2026-05-12T18:31:04.000Z"
  },
  "previousStatus": "pending_aml",
  "invite": {
    "identityType": "email",
    "identityValue": "alice@example.com",
    "batchId": "uuid-or-null"
  }
}

contract.created

{
  "appId": "65f...",
  "contract": {
    "id": "8a3...",
    "name": "Invoice #1042",
    "code": "INV-1042",
    "contractType": "Invoice"
  },
  "paymentData": null
}

payment.attached

{
  "appId": "65f...",
  "contract": { "id": "8a3...", "name": "Invoice #1042" },
  "paymentData": {
    "id": "9b2...",
    "amount": 250,
    "paymentDate": "2026-05-12T18:31:04.000Z",
    "transactionHash": "0xabc..."
  }
}

Retries and idempotency

Pvium retries failed deliveries with increasing delays between attempts. Store an identifier for each processed event and skip duplicate deliveries. Use the following identifiers for each event type:

batch.funded and batch.payee.claimed — the transactionHash
payment.attached — paymentData.id
oauth.invite.accepted and oauth.authorization.activated — authorization.id
batch.payee.added — invite.id or authorization.id

Acknowledge quickly with a 2xx and process asynchronously, and reconcile against payout records rather than relying on webhooks alone — records are the source of truth for settled payments.

Get started

Payout automation

Concepts

Delivery format

Verifying deliveries

Events

Payloads

Retries and idempotency

​Delivery format

​Verifying deliveries

​Events

​Payloads

​Retries and idempotency

Delivery format

Verifying deliveries

Events

Payloads

Retries and idempotency