​
Overview

You can now test card scenarios and their webhook events fully end-to-end in Sandbox. Webhook events will be delivered to your external webhook endpoint. This page provides a brief overview of how to set up a webhook endpoint.

​
Testing webhooks

​
1. Set Up Webhook Endpoint

To create a webhook endpoint, you can POST to v0/webhooks as you would in production. By default, webhook endpoints receive events of all categories. To receive just card-related events in your endpoint, you could make a request like the following: 
{
    "url": "https://example.com/api/webhooks/bridge_webhook_event_testing",
    "event_epoch": "beginning_of_time",
	"event_categories": ["card_account", "card_transaction", "posted_card_account_transaction", "card_withdrawal"]
}
You should use a more accurate event_epoch as your event epoch in your integration.
In a successful response, you should receive a payload like the following: 
{
    "id": "wep_tir8iiYS3khF4TqEe7jpKje",
    "url": "https://example.com/api/webhooks/bridge_webhook_event_testing",
    "status": "disabled",
	"event_categories": ["card_account", "card_transaction", "posted_card_account_transaction", "card_withdrawal"]
    "public_key": "-----BEGIN PUBLIC KEY-----<KEY>-----END PUBLIC KEY-----\n",
    "created_at": "2025-02-11T00:42:08.581Z",
    "updated_at": "2025-02-11T00:42:08.806Z"
}

​
2. Activate the webhook endpoint

To activate the webhook endpoint, you can send a PUT request to v0/webhooks/{webhook\_id} just as you would in production. The webhook_id is the same id returned from the response of the POST request from the previous step. To activate the endpoint, you set the status with a payload like so: 
...
{
    "status": "active"
}
...
In a successful response, you should see a payload like the following: 
{
    "id": "wep_tir8iiYS3khF4TqEe7jpKje",
    "url": "https://example.com/api/webhooks/bridge_webhook_event_testing",
    "status": "active",
    "public_key": "-----BEGIN PUBLIC KEY-----<KEY>-----END PUBLIC KEY-----\n",
    "created_at": "2025-02-11T00:42:08.581Z",
    "updated_at": "2025-02-11T03:03:30.918Z"
}

​
3. View Webhook Events

Webhook deliveries now work fully in sandbox, so you should be able to see webhook events delivered to your endpoint without manually testing using the /events endpoint.
To view events that would be sent to an endpoint, you can send a GET request to https://api.sandbox.bridge.xyz/v0/webhooks/{webhook_id}/events. The webhook_id is the same as per the previous. No payload is required, but in sandbox you can pass in a category query parameter to specify which exact events you would like in the payload. For example, to see card account specific events, you can GET https://api.sandbox.bridge.xyz/v0/webhooks/{webhook_id}/events?category=card_account. The response will have a format like so: 
{
    "data": [
        {
            "api_version": "v0",
            "event_id": "wh_tn3ZFia7M5541nzLVJDtj8P",
            "event_sequence": 2,
            "event_category": "card_account",
            "event_type": "card_account.updated.status_transitioned",
            "event_object_id": "f1843b06-1e80-430e-8e13-51999cf66fb8",
            "event_object_status": "active",
            "event_object": {
                "id": "f1843b06-1e80-430e-8e13-51999cf66fb8",
                "status": "active",
                "freezes": [],
                "balances": {
                    "hold": {
                        "amount": "100.0",
                        "currency": "usdc"
                    },
                    "available": {
                        "amount": "200.0",
                        "currency": "usdc"
                    }
                },
                "customer_id": "7e3de6c3-2848-4fe4-9651-b287f464257e",
                "card_details": {
                    "bin": "1234",
                    "expiry": "03/30",
                    "last_4": "0000"
                },
                "card_image_url": "https://<image_url>",
                "funding_instructions": {
                    "chain": "base",
                    "address": "0xdeadbeef2usdcbase5fe073f0-67ef-4d9b-906b-a859f22baf56",
                    "currency": "usdc"
                }
            },
            "event_object_changes": {
                "status": [
                    "frozen",
                    "active"
                ],
                "freezes": [
                    [
                        {
                            "reason": "lost_or_stolen",
                            "ending_at": null,
                            "initiator": "developer",
                            "created_at": "2025-02-11T03:03:28Z",
                            "starting_at": null,
                            "reason_detail": null
                        }
                    ],
                    []
                ],
                "card_image_url": [
                    "https://<image_url>",
                ]
            },
            "event_created_at": "2025-02-11T03:03:37.680Z"
        }
    ]
}