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

# Configure Export Webhooks and File Formats

> Configure a webhook URL to receive mapping export files automatically when a job completes, manage multiple endpoints, and set your preferred export format.

Mapping.Travel can deliver export files to your server automatically when a mapping job finishes. You register one or more webhook URLs, and the API sends an HTTP POST to each active endpoint once the export is ready. You can also trigger an export manually for any completed job and configure the file format you want to receive.

## Register a webhook endpoint

Send a POST request to `/api/v1/export-webhooks` with your endpoint URL. Set `active` to `true` to start receiving deliveries immediately.

```bash theme={null} theme={null}
curl -X POST https://api.mapping.travel/api/v1/export-webhooks \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.example.com/webhooks/mapping-export",
    "active": true
  }'
```

Response:

```json theme={null} theme={null}
{
  "id": "wh-11111111-aaaa-bbbb-cccc-dddddddddddd",
  "url": "https://your-server.example.com/webhooks/mapping-export",
  "active": true,
  "createdAt": "2026-04-25T10:00:00Z",
  "updatedAt": "2026-04-25T10:00:00Z"
}
```

Save the `id` — you need it to update or delete this webhook later.

## Manage your webhooks

<Steps>
  <Step title="List all webhooks">
    Retrieve all webhooks for your organization. Pass `activeOnly=true` to filter to enabled endpoints only.

    <CodeGroup>
      ```bash All webhooks theme={null} theme={null}
      curl https://api.mapping.travel/api/v1/export-webhooks \
        -H "Authorization: Bearer <your-token>"
      ```

      ```bash Active webhooks only theme={null} theme={null}
      curl "https://api.mapping.travel/api/v1/export-webhooks?activeOnly=true" \
        -H "Authorization: Bearer <your-token>"
      ```
    </CodeGroup>
  </Step>

  <Step title="Update a webhook">
    Use PUT to change the URL or toggle the `active` flag. You can disable a webhook without deleting it by setting `active` to `false`.

    ```bash theme={null} theme={null}
    curl -X PUT \
      https://api.mapping.travel/api/v1/export-webhooks/wh-11111111-aaaa-bbbb-cccc-dddddddddddd \
      -H "Authorization: Bearer <your-token>" \
      -H "Content-Type: application/json" \
      -d '{
        "url": "https://your-server.example.com/webhooks/mapping-export",
        "active": false
      }'
    ```
  </Step>

  <Step title="Delete a webhook">
    To permanently remove a webhook, send a DELETE request. The response is `204 No Content`.

    ```bash theme={null} theme={null}
    curl -X DELETE \
      https://api.mapping.travel/api/v1/export-webhooks/wh-11111111-aaaa-bbbb-cccc-dddddddddddd \
      -H "Authorization: Bearer <your-token>"
    ```
  </Step>
</Steps>

## Webhook payload

When a mapping job completes, Mapping.Travel sends a POST request to each active webhook URL. The payload is a JSON object describing the completed export file, including a download URL, the associated mapping job ID, file format, and metadata such as file size and row count.

Your endpoint must return a `2xx` status code within a reasonable timeout. If delivery fails, Mapping.Travel will retry with exponential backoff.

<Warning>
  Make sure your webhook endpoint is publicly reachable from the internet. Endpoints behind a firewall or on `localhost` will not receive deliveries.
</Warning>

## Securing your webhook

To verify that incoming requests come from Mapping.Travel and not a third party:

* **Check the source IP** — Mapping.Travel sends deliveries from a fixed set of IP addresses. Contact support to get the current IP allowlist.
* **Use a secret token in the URL** — Add a hard-to-guess token as a query parameter or path segment when registering your webhook URL (e.g. `https://your-server.example.com/webhooks/mapping-export?secret=abc123`). Validate it on every incoming request.
* **Verify the payload shape** — Reject any delivery that doesn't match the expected export payload structure.

<Note>
  Do not put your Mapping.Travel API token in the webhook URL. Use a separate secret known only to your server.
</Note>

## Configure export format

Set the file format for all exports from your organization. Send a PUT request to `/api/v1/export-format`.

```bash theme={null} theme={null}
curl -X PUT https://api.mapping.travel/api/v1/export-format \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "CSV"
  }'
```

To retrieve your current format configuration:

```bash theme={null} theme={null}
curl https://api.mapping.travel/api/v1/export-format \
  -H "Authorization: Bearer <your-token>"
```

If no format has been configured, the endpoint returns `404 Not Found`.

## Trigger a manual export

You can request an export for any completed mapping job without waiting for a new job to finish. This is useful for re-delivering results to a webhook or generating a fresh download.

```bash theme={null} theme={null}
curl -X POST \
  https://api.mapping.travel/api/v1/mapping/f9e8d7c6-b5a4-3210-fedc-ba9876543210/export \
  -H "Authorization: Bearer <your-token>"
```

Response:

```json theme={null} theme={null}
{
  "success": true,
  "exportFileId": "ef-99887766-5544-3322-1100-aabbccddeeff",
  "message": "Export triggered successfully"
}
```

The export is delivered to all active webhooks once it is ready. If you have no active webhooks, the export file is still generated and can be downloaded separately.

<Tip>
  Use manual export when you add a new webhook and want to re-deliver results from a job that already completed.
</Tip>