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.

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:

{
  "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

1. List all webhooks

   Retrieve all webhooks for your organization. Pass activeOnly=true to filter to enabled endpoints only.

   All webhooks

   curl https://api.mapping.travel/api/v1/export-webhooks \
     -H "Authorization: Bearer <your-token>"
   
2. 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.

   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
     }'
   
3. Delete a webhook

   To permanently remove a webhook, send a DELETE request. The response is 204 No Content.

   curl -X DELETE \
     https://api.mapping.travel/api/v1/export-webhooks/wh-11111111-aaaa-bbbb-cccc-dddddddddddd \
     -H "Authorization: Bearer <your-token>"
   

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.

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

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.

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

Configure export format

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

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:

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.

curl -X POST \
  https://api.mapping.travel/api/v1/mapping/f9e8d7c6-b5a4-3210-fedc-ba9876543210/export \
  -H "Authorization: Bearer <your-token>"

Response:

{
  "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.

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