Skip to main content

Managing Webhook Targets

A target is a URL that receives your webhooks. You can configure up to 5 targets per workspace, disabled ones included.

You can manage targets in two places, and both see the same targets:

  • The API (/api/v2/webhooks/targets, below). A target created here receives every event; filter on type in your own handler if you only need some.
  • The dashboard (Notifications › Webhook). A target created or edited there receives only the categories selected for it: accounts, compliance, banking, crypto, wallets, trade. See the event tables for which event belongs to which category. The dashboard also shows each target's delivery log and can resend failed deliveries.

The dashboard is at https://dashboard.blockwyre.com (sandbox: https://dashboard-sandbox.blockwyre.com), under Notifications › Webhook. The admin.blockwyre.com and admin-sandbox.blockwyre.com hosts are BlockWyre's staff consoles, not the dashboard.

Authentication​

Sign these requests like every other API request, with a workspace-scoped API key:

Authorization: APIKey <signed_jwt>

An account-scoped key is refused with 403. How to build and sign the JWT: Authentication.

StatusMeaning
401The key, its signature or one of its claims failed verification. Body: {"code":401,"message":"unauthorized"}
403The key is valid but account-scoped. Body: {"code":403,"message":"forbidden"}

Add a target​

POST /api/v2/webhooks/targets
Authorization: APIKey <signed_jwt>
Content-Type: application/json

{
  "url": "https://merchant.example.com/blockwyre/webhook"
}

200 OK

{
  "id": "019f1234-5678-90ab-cdef-1234567890ab",
  "url": "https://merchant.example.com/blockwyre/webhook",
  "createdAt": "2026-02-12T18:10:00Z"
}
StatusMeaning
400The body is not valid JSON
409That URL is already a target in this workspace, or you already have 5

Use an absolute https:// URL whose host resolves to a public internet address. This endpoint does not check that: a target on localhost, an internal name, or a private, loopback or link-local address is accepted, but BlockWyre refuses to connect to it, so its first delivery fails all six attempts and the target is disabled. The dashboard checks the host when you save a target and refuses it with webhook_url_not_public.

List targets​

GET /api/v2/webhooks/targets
Authorization: APIKey <signed_jwt>

200 OK

{
  "data": [
    {
      "id": "019f1234-5678-90ab-cdef-1234567890ab",
      "url": "https://merchant.example.com/blockwyre/webhook",
      "createdAt": "2026-02-12T18:10:00Z"
    }
  ]
}
How to tell a target is disabled

disabledAt is absent while a target is healthy, and carries a timestamp once the target has been disabled. Test for the field's presence — do not compare it against a zero date, which is not what the API returns.

A disabled target looks like this:

{
  "id": "019f1234-5678-90ab-cdef-1234567890ab",
  "url": "https://merchant.example.com/blockwyre/webhook",
  "createdAt": "2026-02-12T18:10:00Z",
  "disabledAt": "2026-03-04T09:22:11Z"
}

Re-enable a disabled target​

A target is disabled automatically when one delivery fails all six attempts (the first and five retries, over about 7 to 14 minutes). Any 2xx or 3xx answer counts as delivered, once redirects have been followed (see Configuration); anything else, a timeout after 30 seconds included, is a failed attempt. Fix whatever was failing first — re-enabling an endpoint that still returns 500 disables it again after the next delivery fails all six attempts.

PATCH /api/v2/webhooks/targets/{targetId}/enable
Authorization: APIKey <signed_jwt>

204 No Content

Events that occurred while the target was disabled are not sent to it later. Reconcile through the API for anything you may have missed. Deliveries that failed, including the one that disabled the target, can be resent from the target's delivery log in the dashboard once it is enabled again.

Delete a target​

DELETE /api/v2/webhooks/targets/{targetId}
Authorization: APIKey <signed_jwt>

204 No Content

Deleting is permanent and frees one of your five slots. A deleted target cannot be restored, and creating it again issues a new id.

Support and Resources​

If you need assistance or have any questions, our support team is here to help. You can contact our support team at support@blockwyre.com.

Stay Updated​

Stay up-to-date with the latest news, updates, and features from BlockWyre by following us on social media:

We are excited to have you on board and look forward to seeing how you leverage BlockWyre's powerful tools to enhance your financial operations. Happy integrating!