Skip to content

Webhooks send real-time notifications to your systems when events occur in your Wallet-as-a-Service organization. As an owner or administrator, you create webhook endpoints, choose which events to subscribe to, and verify delivery signatures.

How webhooks work

When a subscribed event occurs (for example, a transaction status changes), Wallet-as-a-Service sends an HTTPS POST request to your configured endpoint. The request body contains a JSON payload with the event details. Wallet-as-a-Service signs each delivery so you can verify it came from the platform.

Create a webhook

  1. Go to Settings > Webhooks.
  2. Select Create webhook.
  3. Enter a name (5–100 characters) that describes the webhook's purpose.
  4. Enter an optional description (5–100 characters).
  5. Enter the URL — the HTTPS endpoint that receives webhook deliveries. The URL must use HTTPS.
  6. Select one or more subscriptions — the event categories that trigger deliveries:
    • Transaction — "All transaction events for this organization"
    • Wallet — "All wallet events for this organization"
    • Approval — "All approval events for this organization"
  7. Select Save.
At least one subscription required

You must select at least one event subscription. You can update the subscriptions at any time after creation.

Verify webhook deliveries

Wallet-as-a-Service signs each webhook delivery with an ECDSA private key. Verify the signature on every delivery to confirm it came from Wallet-as-a-Service and wasn't tampered with. Wallet-as-a-Service retries failed deliveries automatically.

  1. Go to Settings > Webhooks.
  2. Select the webhook to view its details.
  3. Copy the public key displayed on the webhook detail page.
  4. In your application, use the public key to verify the signature included in each delivery's headers.

See Manage webhooks for code examples in Python, JavaScript, and Go.

Update a webhook

  1. Go to Settings > Webhooks.
  2. Select the webhook you want to modify.
  3. Select Edit.
  4. Update the name, description, URL, or event subscriptions.
  5. Select Save.

Delete a webhook

  1. Go to Settings > Webhooks.
  2. Select the webhook.
  3. Select Delete.
  4. Confirm the deletion.

Wallet-as-a-Service stops sending deliveries to the endpoint immediately after deletion.

Webhooks vs. audit logging

Wallet-as-a-Service offers two notification mechanisms. Use both together for complete visibility.

FeatureWebhooksAudit logging
DeliveryReal-time HTTPS push to your endpointWallet-as-a-Service batches deliveries to AWS Firehose (~15 second buffer)
ScopeSubscribed event types only (transactions, wallets, approvals)All API calls and console actions
Use caseTrigger downstream workflows, such as updating your database when a transaction confirmsCompliance reporting, incident investigation, access review
RetentionYour endpoint processes and storesYour Firehose destination (S3, Splunk, etc.)

See Configure audit logging for Firehose setup.

Best practices

  • Use HTTPS only — webhook URLs must use HTTPS. This protects event payloads in transit.
  • Verify signatures on every delivery — never process a webhook payload without verifying the signature first.
  • Implement idempotent processing — your endpoint may receive the same event more than once. Use the event ID to deduplicate.
  • Respond with 2xx quickly — return a 2xx status code as soon as you receive the webhook. Process the payload asynchronously to avoid timeouts.
  • Monitor for failures — set up alerting on your endpoint to detect delivery failures or downtime.
  • Use webhooks instead of polling — for production integrations, webhooks are more efficient and timely than polling the API for status changes.

Manage API credentials

Configure asset sweeping