Webhook Implementation

Overview

As part of the Slicker integration, you need to implement webhook endpoints that Slicker will call to deliver optimization decisions and dunning instructions to your billing system. All webhook events use a unified structure with a consistent envelope format.

Implementation Requirements

Endpoint Configuration

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

Authentication

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

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.

Unified Event Structure

All webhook events use a consistent envelope format:

{
  "id": "evt_2uqkAo1bwllmzrgV2qtGv48DtGI",
  "type": "recovery_action",
  "created": "2023-01-18T09:00:00Z",
  "data": {
    // Event-specific fields
  }
}

Common Fields

Field	Type	Description
`id`	string	Unique identifier for this webhook event
`type`	string	Event type identifier (e.g., `recovery_action`, `pause_collection`, `complete_dunning`)
`created`	string	ISO 8601 timestamp of when the webhook was created
`data`	object	Event-specific payload that varies based on the event type

Event Types

Recovery Action Event

Sent when a payment should be retried:

{
  "id": "evt_2uqkAo1bwllmzrgV2qtGv48DtGI",
  "type": "recovery_action",
  "created": "2023-01-18T09:00:00Z",
  "data": {
    "invoiceId": "inv_12345678",
    "subscriptionId": "sub_12345678",
    "actionSuggestion": "ACTION_SUGGESTION_RETRY",
    "idealRetryTime": "2023-01-18T09:30:00Z"
  }
}

Action Suggestion Values:

ACTION_SUGGESTION_RETRY: Attempt to process the payment again
ACTION_SUGGESTION_CARD_CHANGE: Request an updated payment method from the customer
ACTION_SUGGESTION_UNSPECIFIED: No specific action recommended

Pause Invoice Collection Event

Sent when automatic retries should be paused. This is used during A/B tests to control which invoices should be retried by Slicker vs your system.

{
  "id": "evt_3vrkBp2cxmmn0shW3ruHw59EuHJ",
  "type": "pause_collection",
  "created": "2023-01-18T10:00:00Z",
  "data": {
    "invoiceId": "inv_12345678"
  }
}

Complete Dunning Event

Sent when dunning should be completed before the dunning period ends.

{
  "id": "evt_4wslCq3dynn1ptiX4svIx60FvIK",
  "type": "complete_dunning",
  "created": "2023-01-18T11:00:00Z",
  "data": {
    "invoiceId": "inv_12345678"
  }
}

Response Format

Your webhook should respond with a 200 OK status code and an optional JSON body if the event was successfully received:

{
  "success": true,
  "message": "Event processed successfully"
}

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 event id to handle potential duplicate webhooks
Return appropriate error codes if requests can’t be processed
Slicker will retry failed webhooks, so ensure idempotency

Retry Policy

Slicker automatically retries failed webhook deliveries using a two-phase strategy: immediate synchronous retries followed by delayed asynchronous retries. A delivery is considered successful when your endpoint returns any 2xx HTTP status code within 30 seconds. Any other response (or a timeout/connection error) is treated as a failure and triggers retries.

Recovery Action Events

Recovery action webhooks are retried up to 6 total attempts:

Attempt	Type	Delay after previous attempt
1	Initial delivery	—
2	Sync retry	~100ms
3	Sync retry	5 seconds
4	Sync retry	15 seconds
5	Async retry	15 minutes
6	Async retry	30 minutes

After 6 failed attempts, the webhook is marked as exhausted and no further retries occur.

Pause Collection & Complete Dunning Events

These event types are retried up to 7 total attempts:

Attempt	Type	Delay after previous attempt
1	Initial delivery	—
2	Sync retry	~100ms
3	Sync retry	5 seconds
4	Sync retry	15 seconds
5	Async retry	15 minutes
6	Async retry	30 minutes
7	Async retry	1 hour

After 7 failed attempts, the webhook is marked as exhausted and no further retries occur.

Handling Retries

Each webhook event has a unique id field. Use this to deduplicate events on your side — you may receive the same event more than once if your endpoint returned a success after Slicker’s timeout window or due to network issues.

Respond quickly: Return a 2xx within 30 seconds. If processing takes longer, acknowledge receipt immediately and process the event asynchronously.
Idempotency: Store the event id and skip processing if you’ve already handled it.
Monitoring: If all retries are exhausted, the event is marked as failed in Slicker’s delivery logs. Contact support if you experience persistent delivery failures.

Monitoring

Set up alerts for failed webhook calls
Monitor webhook endpoint uptime

Reference Documentation

For detailed API specifications, see:

Support

If you need assistance with your webhook implementation:

Contact your Slicker integration specialist
Email support@slickerhq.com

Integrations

Billing & Subscriptions

Payment providers

Webhook Implementation

Overview

Implementation Requirements

Endpoint Configuration

Authentication

Bearer Token Authentication

Basic Authentication

Unified Event Structure

Common Fields

Event Types

Recovery Action Event

Pause Invoice Collection Event

Complete Dunning Event

Response Format

Implementation Best Practices

Security

Reliability

Retry Policy

Recovery Action Events

Pause Collection & Complete Dunning Events

Handling Retries

Monitoring

Reference Documentation

Support

​Overview

​Implementation Requirements

​Endpoint Configuration

​Authentication

​Bearer Token Authentication

​Basic Authentication

​Unified Event Structure

​Common Fields

​Event Types

​Recovery Action Event

​Pause Invoice Collection Event

​Complete Dunning Event

​Response Format

​Implementation Best Practices

​Security

​Reliability

​Retry Policy

​Recovery Action Events

​Pause Collection & Complete Dunning Events

​Handling Retries

​Monitoring

​Reference Documentation

​Support

Overview

Implementation Requirements

Endpoint Configuration

Authentication

Bearer Token Authentication

Basic Authentication

Unified Event Structure

Common Fields

Event Types

Recovery Action Event

Pause Invoice Collection Event

Complete Dunning Event

Response Format

Implementation Best Practices

Security

Reliability

Retry Policy

Recovery Action Events

Pause Collection & Complete Dunning Events

Handling Retries

Monitoring

Reference Documentation

Support