HTTP Request

Send data to any HTTP endpoint with full control over method, headers, authentication, and payload format. Use Zeotap to integrate with custom REST APIs, internal microservices, serverless functions, or any system that accepts HTTP requests.

Prerequisites

• An HTTP endpoint that accepts POST, PUT, PATCH, or DELETE requests
• The endpoint must be reachable from Zeotap over the network
• An authorization header value or API key (if the endpoint requires authentication)

Authentication

HTTP Request uses Authorization Header authentication. Both fields are optional — use whichever your endpoint requires.

Configuration

Target Settings

HTTP Request does not require additional target settings. Data is sent directly to the configured URL.

Supported Operations

Sync Modes

Audience Sync Modes

Features

How It Works

Zeotap sends data to your HTTP endpoint according to the configured batch mode, method, and content type.

Array Batch Mode (default)

All rows in a batch are collected into a single JSON payload and sent as one HTTP request:

1. Rows are collected into a batch and serialized as a JSON object containing a rows array
2. An HTTP request is made to the configured URL using the selected method
3. Authentication headers are applied automatically
4. Custom headers are merged into the request
5. The X-Sync-Mode and X-Batch-Size headers are set for downstream routing

Request format:

{
  "sync_mode": "upsert",
  "rows": [
    {
      "data": {
        "email": "user@example.com",
        "name": "Jane Doe",
        "score": 85
      },
      "operation": "added",
      "primary_key": "user-123"
    },
    {
      "data": {
        "email": "john@example.com",
        "name": "John Smith",
        "score": 92
      },
      "operation": "changed",
      "primary_key": "user-456"
    }
  ]
}

Individual Batch Mode

Each row is sent as a separate HTTP request, giving you per-row control and error isolation:

1. Each row generates its own HTTP request
2. Failed rows are tracked individually without blocking the rest of the batch
3. The X-Sync-Mode and X-Row-Operation headers indicate the sync mode and diff operation for each request

JSON request format (per row):

{
  "data": {
    "email": "user@example.com",
    "name": "Jane Doe",
    "score": 85
  },
  "operation": "added",
  "primary_key": "user-123"
}

Form URL-encoded format (per row):

When Content Type is set to application/x-www-form-urlencoded, each row is sent as form data:

email=user%40example.com&name=Jane+Doe&score=85

Metadata Headers

Every request includes these headers for downstream routing:

Response Handling

• 2xx responses: Treated as successful delivery
• Non-2xx responses: Treated as failures; the HTTP status code and response body are reported in the sync log
• Retries: Failed requests are automatically retried up to 3 times with exponential backoff

Rate Limits

HTTP Request does not impose its own rate limits. Rate limiting depends entirely on the target endpoint. If the endpoint returns HTTP 429 (Too Many Requests), Zeotap respects the Retry-After header and retries with backoff.

For high-volume syncs to rate-limited endpoints, consider using Array batch mode to reduce the number of requests.

Best Practices

• Use array batch mode for most use cases — it reduces HTTP overhead and is more efficient for bulk data transfer
• Use individual batch mode when you need per-row error isolation or the endpoint only accepts single records
• Set explicit Content-Type if your endpoint requires form-encoded data rather than JSON
• Add custom headers for routing, versioning, or tracing (e.g., X-API-Version, X-Trace-ID)
• Use HTTPS for production endpoints to encrypt data in transit
• Implement idempotency on your endpoint using the primary_key field to handle retries safely
• Monitor sync logs for HTTP error codes to detect authentication expiry or endpoint issues early

Troubleshooting

Connection failed

Verify the request URL is correct and reachable from Zeotap. Check that the endpoint is running and accepting connections. For internal services, ensure network routing and firewall rules allow traffic from Zeotap.

Authentication failed (401/403)

Verify the Authorization header value is correct and properly formatted. For Bearer tokens, ensure the token has not expired. For API keys, confirm the key is active and has the necessary permissions.

Invalid URL

The request URL must start with http:// or https://. Relative URLs, WebSocket URLs (ws://), and other protocols are not supported.

Endpoint returning 500 errors

Server errors trigger automatic retries with exponential backoff (up to 3 retries). If errors persist, check the endpoint’s logs for the root cause. Ensure the endpoint can handle the JSON payload format and the expected volume of requests.

Timeout errors

Zeotap uses a 120-second request timeout. For slow endpoints, ensure the server responds within this window. Long-running processing should be handled asynchronously by the endpoint — acknowledge receipt quickly and process in the background.

Form-encoded data not working

Form URL-encoded content type is only supported in Individual batch mode. In Array batch mode, the payload is always serialised as JSON and the Content-Type header is forced to application/json regardless of the configured Content-Type. Switch to Individual mode if your endpoint requires form-encoded data. Note that in form-encoded Individual mode, the sync_mode, operation, and primary_key metadata are not included in the body — they are delivered via the X-Sync-Mode, X-Row-Operation, and X-Primary-Key headers instead.

Custom headers not being sent

Ensure custom headers are formatted as a valid JSON object (e.g., {"X-Custom": "value"}). Invalid JSON in the Custom Headers field is silently ignored. Note that Authorization and X-Api-Key headers set via the Authentication section take precedence over the same keys in Custom Headers.

Rows failing individually

In Individual batch mode, each row is sent as a separate request. Check the sync log for per-row errors including the HTTP status code and response body. Common causes include data validation failures on the endpoint or missing required fields in specific rows.