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

# Send Test Webhook

> Send a realistic, signed test event to your Tuco webhook: heartbeat, message sent (attachment, voice note, P2P SMS), reply, fallback and more.

Sends a test event to your webhook endpoint, signed with your webhook secret exactly like a live delivery. Each test payload is built by the same code that builds live webhooks, so a test that passes means your parser handles the real event.

Tests are marked with the `X-Tuco-Test: true` header and `"testMode": true` in the body. They appear in the [delivery log](/api-reference/endpoint/list-webhook-deliveries) and never count as failures on your webhook.

## Authentication

```bash theme={null}
Authorization: Bearer tuco_xxxxxxxxxxxxx
```

## Path parameters

<ParamField path="id" type="string" required>
  Webhook ID.
</ParamField>

## Body

Send no body to test every event the webhook subscribes to (one request per event).

<ParamField body="event" type="string">
  Send only this event. Any event below, including `heartbeat`, even if the webhook is not subscribed to it.
</ParamField>

<ParamField body="variant" type="string">
  Payload variant for the event. Defaults to the first variant listed for that event.
</ParamField>

| `event` | `variant` (first is the default) |
| - | - |
| `heartbeat` | `default` |
| `message.sent` | `text`, `attachment`, `pdf`, `link`, `voice_note`, `p2p_sms` |
| `message.reply` | `text`, `attachment`, `pdf`, `voice_note` |
| `message.failed` | `strike_2`, `expired` |
| `message.fallback` | `default` |
| `message.opened` | `default` |
| `message.reaction` | `default` |
| `message.ai_draft` | `default` |
| `message.ai_draft_approved` | `default` |
| `message.ai_draft_rejected` | `default` |
| `conversation.handover` | `default` |
| `call.recording.ready` | `default` |

## Response

<ResponseField name="ok" type="boolean">`true` when every test got a `2xx`.</ResponseField>
<ResponseField name="status" type="number">Your endpoint's HTTP status for the first failing test, or the last test.</ResponseField>
<ResponseField name="statusText" type="string">Status text, or `Timeout (10s)` / the network error.</ResponseField>
<ResponseField name="latency" type="number">Milliseconds for that request.</ResponseField>
<ResponseField name="body" type="string">First 500 characters of your endpoint's last response.</ResponseField>
<ResponseField name="results" type="array">One entry per test: `event`, `variant`, `ok`, `status`, `statusText`, `latency`.</ResponseField>

| Status | When |
| - | - |
| `200` | Tests were sent (check `ok` for your endpoint's result) |
| `400` | Unknown `event` or `variant`, invalid JSON, or the webhook is inactive |
| `401` | Missing or invalid API key |
| `404` | Webhook not found in your workspace |

## Examples

```bash theme={null}
curl -X POST "https://app.tuco.ai/api/webhooks/680a1b2c3d4e5f6789012345/test" \
  -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"event": "message.sent", "variant": "p2p_sms"}'
```

<CodeGroup>
  ```json heartbeat theme={null}
  {
    "event": "heartbeat",
    "testMode": true,
    "timestamp": "2026-10-15T21:26:17.747Z",
    "workspaceId": "org_xxx",
    "data": {}
  }
  ```

  ```json message.sent · p2p_sms theme={null}
  {
    "event": "message.sent",
    "timestamp": "2026-10-15T21:26:17.748Z",
    "workspaceId": "org_xxx",
    "leadId": "7e57ab1e0000000000000001",
    "lead": {
      "_id": "7e57ab1e0000000000000001",
      "firstName": "Test",
      "lastName": "Contact",
      "email": "test.contact@example.com",
      "phone": "+15551234567",
      "companyName": "Test Co",
      "listId": "7e57ab1e0000000000000004",
      "workspaceId": "org_xxx",
      "source": "api",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z"
    },
    "messageId": "7e57ab1e0000000000000002",
    "message": {
      "_id": "7e57ab1e0000000000000002",
      "message": "This is a test webhook from Tuco. If you see this, your endpoint is working correctly.",
      "messageType": "imessage",
      "direction": "sent",
      "recipientPhone": "+15551234567",
      "recipientName": "Test Contact",
      "fromLineId": "7e57ab1e0000000000000003",
      "fromLinePhone": "+15557654321",
      "fromLineEmail": "line@example.com",
      "leadId": "7e57ab1e0000000000000001",
      "source": "api",
      "workspaceId": "org_xxx",
      "createdByUserId": "user_test",
      "status": "sent",
      "externalMessageId": "TEST-0000-0000-0000-000000000001",
      "createdAt": "2026-10-15T21:26:17.748Z",
      "updatedAt": "2026-10-15T21:26:17.748Z",
      "sentAt": "2026-10-15T21:26:17.748Z",
      "smsForwarded": true,
      "smsForwardedAt": "2026-10-15T21:26:17.748Z",
      "smsForwardedMethod": "apple-script"
    },
    "contactOwnerEmail": null,
    "ghlContactId": null,
    "ghlLocationId": null,
    "hsPortalId": null,
    "hsContactId": null,
    "channel": "p2p_sms",
    "data": {},
    "testMode": true
  }
  ```

  ```json message.reply · attachment theme={null}
  {
    "event": "message.reply",
    "timestamp": "2026-10-15T21:26:17.749Z",
    "workspaceId": "org_xxx",
    "leadId": "7e57ab1e0000000000000001",
    "lead": {
      "_id": "7e57ab1e0000000000000001",
      "firstName": "Test",
      "lastName": "Contact",
      "email": "test.contact@example.com",
      "phone": "+15551234567",
      "companyName": "Test Co",
      "listId": "7e57ab1e0000000000000004",
      "workspaceId": "org_xxx",
      "source": "api",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z"
    },
    "messageId": "7e57ab1e0000000000000006",
    "message": "",
    "firstName": "Test",
    "lastName": "Contact",
    "phone": "+15551234567",
    "listId": "7e57ab1e0000000000000004",
    "fromLineId": "7e57ab1e0000000000000003",
    "recipientName": "Test Contact",
    "contactOwnerEmail": null,
    "repliedAtUtc": "2026-10-15T21:26:17.748Z",
    "parentMessages": [],
    "ghlContactId": null,
    "ghlLocationId": null,
    "hsPortalId": null,
    "hsContactId": null,
    "optedOut": false,
    "attachmentUrls": [
      "https://example.private.blob.vercel-storage.com/tuco-test/photo.jpeg"
    ],
    "attachmentDownloadUrls": [
      "https://app.tuco.ai/api/attachments/crm-media/photo.jpeg?u=aHR0cHM6Ly9leGFtcGxlLnByaXZhdGUuYmxvYi52ZXJjZWwtc3RvcmFnZS5jb20vdHVjby10ZXN0L3Bob3RvLmpwZWc&exp=1794691577749&sig=T4YoMYGXdllKOG1bS-yVmbdD9njn-gfW98c4Gi3SA2M"
    ],
    "attachmentNames": [
      "photo.jpeg"
    ],
    "data": {
      "reply": {
        "leadId": "7e57ab1e0000000000000001",
        "messageId": "7e57ab1e0000000000000006",
        "respondedAtUtc": "2026-10-15T21:26:17.748Z",
        "recipientPhone": "+15551234567",
        "name": "Test Contact",
        "recentReplies": [],
        "parentMessages": [],
        "attachmentUrls": [
          "https://example.private.blob.vercel-storage.com/tuco-test/photo.jpeg"
        ],
        "attachmentDownloadUrls": [
          "https://app.tuco.ai/api/attachments/crm-media/photo.jpeg?u=aHR0cHM6Ly9leGFtcGxlLnByaXZhdGUuYmxvYi52ZXJjZWwtc3RvcmFnZS5jb20vdHVjby10ZXN0L3Bob3RvLmpwZWc&exp=1794691577749&sig=T4YoMYGXdllKOG1bS-yVmbdD9njn-gfW98c4Gi3SA2M"
        ],
        "attachmentNames": [
          "photo.jpeg"
        ]
      },
      "repliedAtUtc": "2026-10-15T21:26:17.748Z",
      "parentMessages": []
    },
    "testMode": true
  }
  ```
</CodeGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.