> For the complete documentation index, see [llms.txt](https://docs.tip4serv.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tip4serv.com/webhooks-developers-only/webhook-responses.md).

# Webhook Responses

This guide explains how to respond to Tip4Serv webhooks, report delivery results globally or per server and command, control when payments or subscriptions are marked as processed, and request retries for unfinished work.

### Response Semantics

#### A) `200 OK` with no body

All orders contained in the event are marked as delivered, and the related payment or subscription is marked as processed. This is the global acknowledgment behavior.

#### B) `200 OK` with targeted JSON

Return `Content-Type: application/json; charset=utf-8` to report delivery results per server or command:

```json
HTTP/1.1 200 OK
Content-Type: application/json

{
  "ok": true,
  "retry_after": 60,
  "results": [
    {
      "server_id": "20859",
      "commands": [
        { "command_id": "0", "delivered": true },
        {
          "command_id": "1",
          "delivered": false,
          "error": "There was a problem here"
        },
        { "command_id": "2", "pending": true }
      ]
    },
    {
      "server_id": "20861",
      "delivered": true
    }
  ]
}
```

#### Retry Behavior

The worker retries webhook deliveries in two situations:

1. **Automatic retry:** your endpoint returns a non-2xx HTTP status, times out, or cannot be reached.
2. **Requested retry:** your endpoint responds with `503 Service Unavailable` and a `Retry-After` header, or returns a successful JSON response that leaves commands pending and specifies `retry_after`.

**Automatic retries**

If your endpoint returns a non-2xx HTTP status code, times out, or is unreachable, Tip4Serv retries the webhook using exponential backoff. The first retry occurs after about 1 minute, with subsequent delays increasing to about 2, 4, and 8 minutes. Tip4Serv makes up to 14 delivery attempts.

If Tip4Serv hasn’t received a successful response after 4 days, automatic retries stop. You can resend the webhook manually from the **Retry Queue** column on the [Webhooks page](https://tip4serv.com/dashboard/webhooks) in your dashboard.

**Requested retries**

Use the `Retry-After` response header to tell Tip4Serv how long to wait before retrying the webhook. This gives your integration time to complete delivery. When the next webhook attempt arrives, return the updated status of each command. Tip4Serv marks each command you report as `delivered` accordingly in the payment details.

### Usage Examples

#### Example 1: Retry after 120 seconds

```http
HTTP/1.1 503 Service Unavailable
Retry-After: 120
Content-Type: text/plain; charset=utf-8

Temporary failure. Please retry later.
```

#### Example 2: Validate everything

```http
HTTP/1.1 200 OK
Content-Length: 0
```

#### Example 3: Validate some commands and retry unfinished work

```json
HTTP/1.1 200 OK
Content-Type: application/json

{
  "ok": true,
  "retry_after": 60,
  "results": [
    {
      "server_id": "20859",
      "commands": [
        { "command_id": "0", "delivered": true },
        {
          "command_id": "1",
          "delivered": false,
          "error": "server unreachable"
        }
      ]
    }
  ]
}
```

#### Example 4: Validate an entire server

```json
HTTP/1.1 200 OK
Content-Type: application/json

{
  "ok": true,
  "results": [
    { "server_id": "20861", "delivered": true }
  ]
}
```

#### Example 5: Specify a d**elivery date for a command**

To specify when a command was delivered, include an optional `date` on its command result. ISO 8601 timestamps are recommended.

If the date is omitted or invalid, the worker uses the time it processed the response.

```json
HTTP/1.1 200 OK
Content-Type: application/json

{
  "ok": true,
  "results": [
    {
      "server_id": "20859",
      "commands": [
        {
          "command_id": "0",
          "delivered": true,
          "date": "2026-10-07T12:00:00.000Z"
        }
      ]
    }
  ]
}
```

### Payment Status Validation

The payment stays **PAID** while any delivery action is pending. Tip4Serv marks it as **PROCESSED** once all delivery actions have reached a final state, including those handled by Discord and other server integrations.

Tip4Serv stops retrying the webhook once you confirm all its commands. The payment can still be **PAID** if another integration has pending actions.

### Resending Commands

When a seller resends one or more commands from the Tip4Serv dashboard, each resent command gets a new `command_id`, while the `request_id` may stay the same. Use the combination of `request_id` and `command_id` to deduplicate each command.&#x20;

This lets you skip commands you’ve already processed on webhook retries while still executing manually resent commands.

### Summary

Tip4Serv sends the commands configured for each event, such as a new payment, subscription renewal, refund, or subscription expiration. Your integration handles commands the same way for every event.

**A webhook can contain no commands.** For example, Tip4Serv still sends a webhook when a subscription renews or a payment is refunded, even if the seller hasn’t configured any commands for that event. If there are no commands to execute, return a `2xx` response to acknowledge receipt.

**Each event has a unique `request_id`.** Webhook retries for the same event reuse that ID.

1. Use `request_id` and `command_id` together to deduplicate commands.
2. Return `delivered: true` once a command has been successfully delivered. If you receive the same pair again, skip execution and return `delivered: true` again.

Tip4Serv handles retries and updates command and payment statuses.
