Skip to main content

​
Endpoint

POST /hooks
Registers a new webhook that will be called when specific events occur in Blnk. Webhooks can be configured to trigger before or after transactions.

​
Request Body

​
name
string
required
A friendly name for the webhook to help identify it
​
url
string
required
The HTTPS URL where webhook events will be sent. Must be a valid URL
​
type
string
required
The type of webhook. Supported values:
  • PRE_TRANSACTION: Called before a transaction is processed (can modify or reject)
  • POST_TRANSACTION: Called after a transaction is completed (notification only)
​
active
boolean
default:"true"
Whether the webhook is active and should receive events
​
timeout
integer
default:"30"
Maximum time to wait for a response from the webhook endpoint, in seconds
​
retry_count
integer
default:"3"
Number of times to retry if the webhook call fails

​
Response

​
id
string
Unique identifier for the webhook
​
name
string
The friendly name of the webhook
​
url
string
The webhook endpoint URL
​
type
string
The webhook type (PRE_TRANSACTION or POST_TRANSACTION)
​
active
boolean
Whether the webhook is currently active
​
timeout
integer
Timeout in seconds
​
retry_count
integer
Number of retry attempts
​
created_at
string
Timestamp when the webhook was created (ISO 8601 format)
​
last_run
string
Timestamp of the last execution (ISO 8601 format)
​
last_success
boolean
Whether the last execution was successful

​
Example Request

​
Pre-Transaction Webhook

{
  "name": "Fraud Detection",
  "url": "https://api.example.com/webhooks/fraud-check",
  "type": "PRE_TRANSACTION",
  "active": true,
  "timeout": 10,
  "retry_count": 1
}

​
Post-Transaction Webhook

{
  "name": "Transaction Notification",
  "url": "https://api.example.com/webhooks/transaction-complete",
  "type": "POST_TRANSACTION",
  "active": true,
  "timeout": 30,
  "retry_count": 3
}

​
Example Response

{
  "id": "hook_abc123def456",
  "name": "Fraud Detection",
  "url": "https://api.example.com/webhooks/fraud-check",
  "type": "PRE_TRANSACTION",
  "active": true,
  "timeout": 10,
  "retry_count": 1,
  "created_at": "2024-03-04T12:00:00Z",
  "last_run": "2024-03-04T00:00:00Z",
  "last_success": false
}

​
Webhook Payload

When your webhook is triggered, it will receive a POST request with the following payload: 
{
  "transaction_id": "txn_123abc",
  "hook_type": "PRE_TRANSACTION",
  "timestamp": "2024-03-04T12:30:00Z",
  "data": {
    "amount": 100.50,
    "currency": "USD",
    "source": "bln_source123",
    "destination": "bln_dest456",
    "reference": "REF-001",
    "description": "Payment"
  }
}

​
Expected Webhook Response

​
For PRE_TRANSACTION Webhooks

Your webhook endpoint must respond with: 
{
  "success": true,
  "message": "Transaction approved",
  "data": {
    "modified_amount": 100.50
  }
}
To reject a transaction: 
{
  "success": false,
  "message": "Transaction blocked due to fraud risk"
}

​
For POST_TRANSACTION Webhooks

Simply acknowledge receipt: 
{
  "success": true,
  "message": "Notification received"
}

​
Error Responses

​
error
string
Error message describing what went wrong

​
Common Errors

  • 400 Bad Request: Invalid request body or URL format
  • 500 Internal Server Error: Failed to register webhook

​
Webhook Types Explained

​
PRE_TRANSACTION

  • Purpose: Validate, modify, or reject transactions before processing
  • Use Cases:
    • Fraud detection
    • Compliance checks
    • Balance verification
    • Transaction modification
  • Behavior: Transaction is blocked until webhook responds
  • Timeout Critical: Yes, must respond quickly

​
POST_TRANSACTION

  • Purpose: Notification after transaction completes
  • Use Cases:
    • Send confirmation emails
    • Update external systems
    • Trigger workflows
    • Logging and analytics
  • Behavior: Fire and forget (doesn’t block transaction)
  • Timeout Critical: No, retries handle failures

​
Best Practices

  1. Use HTTPS: Always use secure HTTPS endpoints
  2. Set appropriate timeouts: PRE_TRANSACTION webhooks should have short timeouts (5-10s)
  3. Implement idempotency: Handle duplicate webhook calls gracefully
  4. Return quickly: Process webhooks asynchronously if possible
  5. Monitor webhook health: Track last_run and last_success fields
  6. Validate payloads: Verify webhook authenticity before processing
  7. Handle retries: Implement proper retry logic for failed webhooks

​
Security Considerations

  1. Verify requests: Implement webhook signature verification
  2. Use IP whitelisting: Restrict access to known Blnk IP addresses
  3. Rate limiting: Protect your endpoint from abuse
  4. Log failures: Monitor and alert on webhook failures

Build docs developers (and LLMs) love

Get started for freeTalk to us