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

# Connection testing

> Trigger a test delivery to verify your destination is configured correctly before relying on it for live jobs.

Every delivery destination can be tested on demand. The test is type-specific: it performs the minimum operations needed to confirm credentials, reachability, and write access — without sending a real result file.

## Run a test

```bash theme={null} theme={null}
curl -X POST \
  https://api.mapping.travel/api/v1/delivery-destinations/{id}/test \
  -H "X-API-Key: <your-token>"
```

Response:

```json theme={null} theme={null}
{
  "success": true,
  "durationMs": 342,
  "error": null
}
```

On failure:

```json theme={null} theme={null}
{
  "success": false,
  "durationMs": 5021,
  "error": "AccessDenied: User is not authorized to perform s3:PutObject on resource arn:aws:s3:::acme-bucket/incoming/.mapping-travel-connection-test-c7f3…"
}
```

The `error` field contains the raw error message from the remote service, which is useful for diagnosing permission and credential issues.

## What each test does

<AccordionGroup>
  <Accordion title="Webhook — synthetic test payload">
    Mapping.Travel sends an HTTP POST to your endpoint URL with a synthetic payload:

    ```json theme={null} theme={null}
    {
      "id": "del_test_01HZ…",
      "eventId": "evt_test_01HZ…",
      "type": "webhook.test",
      "apiVersion": "2026-06-01",
      "createdAt": "2026-06-07T12:00:00Z",
      "data": {
        "destinationId": "dest_01HZ…"
      }
    }
    ```

    The payload is signed with `X-Webhook-Signature` using the destination's current signing secret. Your endpoint should return `2xx` and can verify the signature the same way it would for a live event.

    The test counts as a single delivery attempt. If your endpoint returns a non-2xx status or doesn't respond within 30 seconds, `success` is `false` and `error` contains the HTTP status or connection error.
  </Accordion>

  <Accordion title="S3 — HeadBucket + PutObject + DeleteObject">
    The test performs three S3 API calls in sequence:

    1. **`HeadBucket`** — verifies the bucket exists and the credentials can reach it.
    2. **`PutObject`** — writes a small probe file at `{pathPrefix}.mapping-travel-connection-test-{uuid}.txt`.
    3. **`DeleteObject`** — removes the probe file to leave the bucket clean.

    If any step fails, the test stops and returns the AWS error in `error`. The probe file is cleaned up even on partial success (steps 1–2 pass, step 3 fails) via a best-effort delete; if cleanup fails, a file named `.mapping-travel-connection-test-*.txt` may remain in the bucket.
  </Accordion>

  <Accordion title="SFTP — connect + upload + delete">
    The test performs three SFTP operations in sequence:

    1. **Connect** — establishes the SSH connection, authenticates (password or key), and verifies the host fingerprint.
    2. **Upload** — writes a small probe file at `{remotePath}.mapping-travel-connection-test-{uuid}.txt`.
    3. **Delete** — removes the probe file.

    If host key verification fails (fingerprint mismatch), the test fails at step 1 with `error: "HOST_KEY_MISMATCH"`. Update `hostFingerprints` on the destination and retry.
  </Accordion>
</AccordionGroup>

## Auto-reactivation on success

If a destination is currently `INACTIVE` (e.g. due to auto-disable from repeated failures), a **successful** test automatically sets its status back to `ACTIVE`. No separate PATCH call is needed.

This makes the test the canonical way to re-enable a destination after you've fixed the underlying issue.

## Running tests from the dashboard

In the app, open **Developers → Delivery destinations**, find the destination row, and click **Test**. The result appears in a drawer with the raw error message (if any) and duration.

## Frequency limits

You can run up to **10 tests per destination per hour**. Attempts beyond this limit return `429 Too Many Requests`.