Skip to content
API Reference/
/
/
/webhook/test

/webhook/test

Request

Sends a test webhook delivery to verify connectivity and signature verification.

Purpose

Allows a partner to trigger a test delivery to their configured webhook endpoint. This verifies that the endpoint is reachable, responds within the timeout, and can process the webhook payload correctly.

When to use

Use this endpoint to:

  • Verify initial webhook integration before going live
  • Test connectivity after changing the webhook URL
  • Debug delivery issues by triggering a controlled delivery
  • Verify signature verification logic is working correctly

What happens next

  1. The webhook configuration is validated (must be active with a signing secret)
  2. A test event payload is constructed and signed with the current webhook_secret
  3. The payload is delivered via HTTP POST to the configured webhook_url
  4. The delivery result (status code, response time, any failure) is returned immediately

Authentication

Requires x-client-id and x-secret-key headers.

Notes

  • The test delivery uses event_type webhook.test which is not a real event
  • The test delivery is NOT logged in the delivery history
  • The webhook must be active and have a signing secret configured
  • Connection timeout: 5 seconds, read timeout: 10 seconds
  • Returns the full delivery result synchronously (no retries for test deliveries)

Common errors

  • 400 Webhook is inactive or missing signing secret
  • 401 Invalid credentials
  • 404 Webhook not found for the given webhook_id
  • 500 Internal error during test delivery
Headers
x-client-idstring, [ 16 .. 64 ] charactersrequired

Unique identifier assigned to the integrating client.

Error codes: required=400001, type=400002, minLength=400003, maxLength=400004

Example:string
x-secret-keystring, [ 32 .. 128 ] charactersrequired

Secret authentication key associated with the client.

Error codes: required=400001, type=400002, minLength=400003, maxLength=400004

Example:string
Bodyapplication/jsonrequired
webhook_idstringrequired

UUID v4 identifier of the webhook to send a test delivery to.

Error codes: required=400001, type=400002

POST
/webhook/test
curl -i -X POST \
  https://sandbox-viablocks.viamericas.io/webhook/test \
  -H 'Content-Type: application/json' \
  -H 'x-client-id: string' \
  -H 'x-secret-key: string' \
  -d '{
    "webhook_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
  }'

Responses

Test delivery completed (check delivery_status for result)

Bodyapplication/json
statusstring

Response status (success)

dataobject

Test delivery result

Response
{
  "status": "success",
  "data": {
    "test_event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "delivery_status": "success",
    "http_status_code": 200,
    "response_time_ms": 145,
    "failure_reason": null,
    "webhook_url": "https://partner.example.com/webhooks/viablocks",
    "signature_header": "sha256=a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"
  }
}