Setup Webhook Subscriptions

To start receive webhook notifications, you need to create a webhook subscription for specific event types.

You can see the avaiable event types at Available Webhook Event Types

The reply will include a secret that will be used to verify the authenticity of webhook requests.

❗️

Store the returned secret securely. It will be used to and cannot be retrieved later.

Endpoint: Webhook Subscription

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "secret": "your_webhook_secret"
}

Manage Webhook Subscriptions

You can manage your webhook subscription by calling the following endpoints:

• Get all webhook subscriptions
• Get webhook details
• Delete wehook subscription

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "callbackUri": "https://your-application.com/webhook-endpoint",
  "callbackMethod": "POST",
  "eventType": "LOAN_APPLICATION_UPDATE",
  "description": "Notification for loan updates",
  "active": true,
  "createdAt": "2023-01-01T12:00:00Z"
}

Receiving Webhooks

When an event occurs that matches one of your subscriptions, Block Earner will send an HTTP request to your callbackUri with the following:

Request Headers

• Content-Type: application/json
• X-API-Signature: A signature for verifying the authenticity of the request
• X-Subscription-ID: The ID of the subscription that triggered this webhook
• X-Event-ID: A unique identifier for this webhook event
• X-Event-Type: The type of event (e.g., LOAN_APPLICATION_APPROVED)

Request Body

The request body will be a JSON object containing details specific to the event type. Each event type has its own payload structure.

Verifying Webhook Signatures

To ensure that webhook requests are genuinely from Block Earner and haven't been tampered with, you should verify the signature included in each request:

1. Extract the X-API-Signature header from the request
2. Concatenate the request body (as a raw string) with your webhook secret
3. Compute the SHA-256 hash of this concatenated string
4. Compare this hash with the value in the X-API-Signature header

Available Webhook Event Types

Block Earner supports the following webhook event types:

Test webhook with your own payload

You can use Testing Webhook endpoint to test any payload you need for your webhook subscription.

1. Get the webhook subscription ID. If you haven't stored it when you made the subscription you can always get it from Get webhook details endpoint

{
  "content": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", // This is your subscription ID
      "callbackUri": "https://api.blockearner.com.au/api/v1/public/webhooks/test/200",
      "callbackMethod": "POST",
      "description": "Optional description of the webhook's purpose.",
      "active": true,
      "eventType": "FIAT_DEPOSIT"
    }
  ],
  "page": {
    "size": 0,
    "number": 0,
    "totalElements": 0,
    "totalPages": 0
  }
}

2. Use the Subscription ID and any JSON payload you want to test in the body. You should receive the payload you triggered in your subscribed webhook

{
  "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "amount": "100.50",
  "fiatCurrency": "AUD"
}