Authorization Webhook Overview

Enterprise Feature: Authorization webhooks are an enterprise-only feature. Please reach out to sales@slash.com to get set up with this functionality.

Overview

Authorization webhooks allow you to implement real-time transaction approval logic by receiving authorization requests before transactions are processed. When a card transaction is initiated, Slash will send a webhook to your configured endpoint, allowing you to approve or decline the transaction based on your custom business logic.

Setup

To begin receiving authorization webhook requests, you’ll need to configure an authorization webhook URL for your account using the account authorization webhook endpoints.

Webhook Headers

Every authorization webhook request includes three important headers for security and validation:

x-webhook-id: A unique identifier for the webhook request
x-webhook-timestamp: The timestamp when the webhook was sent (Unix timestamp)
x-webhook-signature: HMAC signature for request validation

Request Validation

Timestamp Validation

The x-webhook-timestamp should be within 2 minutes of receiving the request to prevent replay attacks.

Signature Validation

To verify that the webhook request actually came from Slash, you should validate the x-webhook-signature header using HMAC SHA256. The signature is created by:

Removing the whsec_ prefix from your signing secret and base64 decoding it
Creating a payload string: {webhookId}.{webhookTimestamp}.{requestBody}
Generating an HMAC SHA256 signature using the decoded secret
Base64 encoding the signature and prefixing with v1=

Here’s a complete example of signature validation:

import crypto from 'crypto';

function validateWebhookSignature(webhookId, webhookTimestamp, signature, body, signingSecret) {
  // Remove whsec_ prefix from signing secret if present
  const secretBase64 = signingSecret.replace('whsec_', '');
  
  // Decode the base64 secret to get the actual signing key
  const decodedSecret = Buffer.from(secretBase64, 'base64');
  
  // Create the payload to sign: webhookId.webhookTimestamp.body
  const payload = `${webhookId}.${webhookTimestamp}.${body}`;
  
  // Generate HMAC SHA256 signature using the decoded secret
  const expectedSignature = crypto
    .createHmac('sha256', decodedSecret)
    .update(payload)
    .digest('base64');
  
  // Extract signature from header (remove 'v1=' prefix)
  const receivedSignature = signature.replace('v1=', '');
  
  // Compare signatures using timing-safe comparison
  return crypto.timingSafeEqual(
    Buffer.from(expectedSignature, 'base64'),
    Buffer.from(receivedSignature, 'base64')
  );
}

Request Timeout

Authorization webhook requests have a default timeout of 1.5 seconds. Your endpoint must respond within this timeframe, or the transaction will be automatically decisioned based on your fallback behavior.

Response Format

Your webhook endpoint must return a 2xx HTTP status code to indicate successful processing. Any non-2xx response will be treated as a failed request. The response body must contain your authorization decision. See the Authorization Webhook Response schema for the complete response format. Example approval response:

{
  "approved": true,
  "reason": "Transaction approved"
}

Example decline response:

{
  "approved": false,
  "reason": "Insufficient funds"
}

Event Schema

The webhook request body contains detailed information about the authorization request. See the Authorization Request Event schema for the complete structure of the event data sent to your webhook.

Debugging and Monitoring

When debugging your authorization webhook behavior, you can view the approval or decline reason directly in the transaction details. This helps you understand how your webhook responses are being processed and troubleshoot any issues.

Fallback Behavior

If your webhook endpoint is unreachable, returns a non-2xx status code, returns an invalid response body, or times out, the transaction will be automatically handled based on your webhook config’s fallbackBehavior:

default: Your transaction will continue to go through our authorization flow (balance and limit checks still apply), and will be treated as if you approved it.
reject: Your transaction will be declined.

The same fallback is applied in the rare case that Slash is operating in a degraded mode where external webhooks cannot be consulted at all — so the fallback you configure fully describes what happens whenever we cannot get an answer from your endpoint.

{
  "fallbackBehavior": "reject"
}

Conditional fallback with `when`

When using fallbackBehavior: "default", you can optionally restrict which transactions are allowed to continue by providing a when condition expression. Transactions matching the condition continue through the standard authorization flow; non-matching transactions are declined. If when is omitted, every transaction continues (the default behavior). when is a small expression tree:

Node	Shape	Semantics
Logical	`{ "operator": "and" \| "or", "left": <condition>, "right": <condition> }`	Combines two sub-conditions; nestable
Amount comparison	`{ "operator": "lte" \| "lt" \| "gte" \| "gt" \| "eq", "field": "amountCents", "value": <integer> }`	Compares the absolute transaction amount in USD cents
Set membership	`{ "operator": "in", "field": "merchantCategoryCode" \| "merchantCountry", "values": [<string>, ...] }`	Matches when the transaction’s field is one of `values`

merchantCategoryCode is the 4-digit MCC and merchantCountry is the ISO 3166-1 alpha-2 country, exactly as delivered on the Authorization Request Event (merchant.categoryCode and merchant.location.country).
A condition over a field the authorization request did not carry evaluates to false (the transaction is declined rather than allowed through).

For example, to auto-approve fallback transactions only when they are at most $20.00 and from MCC 7311:

{
  "fallbackBehavior": "default",
  "when": {
    "operator": "and",
    "left": { "operator": "lte", "field": "amountCents", "value": 2000 },
    "right": { "operator": "in", "field": "merchantCategoryCode", "values": ["7311"] }
  }
}

Or to continue for small transactions or any US transaction:

{
  "fallbackBehavior": "default",
  "when": {
    "operator": "or",
    "left": { "operator": "lte", "field": "amountCents", "value": 1000 },
    "right": { "operator": "in", "field": "merchantCountry", "values": ["US"] }
  }
}

The when condition only applies to the fallback path — if your endpoint responds in time with a valid decision, that decision is always respected. See the Authorization Webhook schema for the full config format.

Overview

Entities

Legal Entity

Account

Account Authorization Webhooks

Virtual Account

Transaction

Transfer Money

Card

Card Group

Invoice

Invoice Series

Expense Report

Customer

Contact

Merchant

Webhooks

Agent Requests

Analytics

Tokens

Authorization Webhook Overview

Overview

Setup

Webhook Headers

Request Validation

Timestamp Validation

Signature Validation

Request Timeout

Response Format

Event Schema

Debugging and Monitoring

Fallback Behavior

Conditional fallback with `when`

​Overview

​Setup

​Webhook Headers

​Request Validation

​Timestamp Validation

​Signature Validation

​Request Timeout

​Response Format

​Event Schema

​Debugging and Monitoring

​Fallback Behavior

​Conditional fallback with when

Overview

Setup

Webhook Headers

Request Validation

Timestamp Validation

Signature Validation

Request Timeout

Response Format

Event Schema

Debugging and Monitoring

Fallback Behavior

Conditional fallback with `when`