> ## Documentation Index
> Fetch the complete documentation index at: https://docs.slickerhq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook Implementation

> How to implement webhook endpoints for receiving events from Slicker

## 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.

```mermaid theme={null}
sequenceDiagram
    participant S as Slicker
    participant Y as Your Webhook Endpoints
    participant B as Your Billing System
    S->>Y: POST /recovery_action (payment retry)
    Y->>Y: Validate request & authenticate
    Y->>B: Forward event data
    B->>B: Process event based on type
    Y->>S: Return 200 OK response
    S->>Y: POST /pause_collection (pause retries)
    Y->>B: Forward event data
    Y->>S: Return 200 OK response
    S->>Y: POST /complete_dunning (dunning complete)
    Y->>B: Forward event data
    Y->>S: Return 200 OK response
```

## 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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

<Info>
  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.
</Info>

* **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:

* [Recovery Action Event](/integrations/billing/custom/api/your/webhooks/recovery_action)
* [Pause Collection Event](/integrations/billing/custom/api/your/webhooks/pause_collection)
* [Complete Dunning Event](/integrations/billing/custom/api/your/webhooks/complete_dunning)

## Support

If you need assistance with your webhook implementation:

* Contact your Slicker integration specialist
* Email [support@slickerhq.com](mailto:support@slickerhq.com)