Skip to main content
mapping.travel delivers export files to your server automatically when a mapping job finishes. 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 set the file format.

​
Register a webhook endpoint

Send a POST request to /api/v1/export-webhooks with your endpoint URL in the webhookUrl field. Set status to ACTIVE to start receiving deliveries immediately.
Response:
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.
2

Update a webhook

Use PUT to change the URL or toggle the status. You can disable a webhook without deleting it by setting status to INACTIVE.
3

Delete a webhook

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

​
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 retries 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 for 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.
To retrieve your current format configuration:
If no format has been configured, the endpoint returns 404 Not Found.

​
Trigger a manual export

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.
Response:
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.