​
Overview

As part of the Slicker integration, you need to implement a webhook endpoint that Slicker will call when it determines a payment should be retried. This webhook is the mechanism by which Slicker delivers its optimization decisions to your billing system.

​
Implementation Requirements

​
Endpoint Configuration

  • Protocol: HTTPS only (unencrypted HTTP is not supported)
  • Method: POST
  • URL: You define the URL and provide it to Slicker during integration setup
  • Content Type: application/json

​
Authentication

Your webhook must implement one of the following authentication methods to ensure that only Slicker can trigger retries:

​
Bearer Token Authentication

Authorization: Bearer YOUR_WEBHOOK_TOKEN

You’ll provide this token to Slicker during integration setup.

​
Basic Authentication

Authorization: Basic base64(username:password)

You’ll provide the username and password to Slicker during integration setup.

​
Request Format

The webhook will receive a JSON payload containing retry instructions:

{
  "requestId": "req_2uqkAo1bwllmzrgV2qtGv48DtGI",
  "invoiceId": "inv_12345678",
  "subscriptionId": "sub_12345678",
  "actionSuggestion": "ACTION_SUGGESTION_RETRY",
  "idealRetryTime": "2023-01-18T09:30:00Z",
}

​
Key Fields

FieldDescription
requestIdUnique identifier for this retry request
invoiceIdIdentifier for the invoice that should be retried
subscriptionIdIdentifier for the subscription associated with the invoice
actionSuggestionType of action to take (RETRY, CARD_CHANGE, etc.)
idealRetryTimeOptimal time to execute the retry according to Slicker’s algorithms

​
Action Suggestion Values

The actionSuggestion field will contain one of the following values:

  • ACTION_SUGGESTION_RETRY: Attempt to process the payment again
  • ACTION_SUGGESTION_CARD_CHANGE: Request an updated payment method from the customer
  • ACTION_SUGGESTION_CARD_CONFIRMATION: Request the customer to confirm their payment method

​
Response Format

Your webhook should respond with a 200 OK status code and a JSON body if the retry instruction was successfully received:

{
  "success": true,
  "message": "Retry scheduled"
}

For error scenarios, use appropriate HTTP status codes (400, 401, 429, 500) and include an error message:

{
  "success": false,
  "error_code": "invalid_request",
  "message": "Invalid format or missing required field"
}

​
Implementation Best Practices

​
Security

  • Use HTTPS with valid SSL certificates
  • Set up authentication with strong credentials
  • (Optional) Implement IP whitelisting (Slicker can provide IP ranges)

​
Reliability

  • Acknowledge receipt quickly and process asynchronously
  • Implement idempotent processing based on request IDs to handle potential duplicate requests
  • Return appropriate error codes if requests can’t be processed

​
Monitoring

  • Log all webhook calls for debugging and auditing
  • Set up alerts for failed webhook calls
  • Monitor webhook endpoint uptime

​
Reference Implementation

For a detailed specification of the webhook API, see the Merchant API Reference.

​
Support

If you need assistance with your webhook implementation: