DestinationsOtherWebhook

Webhook

Send data to any HTTP endpoint. Use Zeotap to integrate with custom APIs, internal services, or any system that accepts JSON payloads over HTTP.

Prerequisites

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

Authentication

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

FieldTypeRequiredDescription
Authorization HeaderPasswordNoValue for the Authorization header (e.g., Bearer your-token)
API KeyPasswordNoAPI key sent in the request (optional, for endpoints that use API key authentication)

Configuration

FieldTypeRequiredDescription
Webhook URLTextYesThe HTTP endpoint to send data to. Must start with http:// or https:// (e.g., https://example.com/webhook)
HTTP MethodSelectNoThe HTTP method to use: POST, PUT, or PATCH. Default: POST

Target Settings

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

Supported Operations

Sync Modes: Insert

Audience Sync Modes: Add, Remove, Mirror, Upsert

Features

  • Field Mapping: No — the full record is sent as a JSON payload
  • Schema Introspection: No — webhooks accept arbitrary JSON

How It Works

Zeotap sends each batch of rows as a single JSON payload to the configured HTTP endpoint:

  1. Rows are collected into a batch and serialized as a JSON array
  2. An HTTP request is made to the webhook URL using the configured method
  3. The Authorization header is set if an authorization header value is configured
  4. The X-Api-Key header is set if an API key is configured
  5. The Content-Type header is set to application/json

Request Format

Each request body contains the sync mode, and an array of rows with their data, operation, and primary key:

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

The operation field reflects the diff status of each row (added, changed, or removed) and is populated for audience syncs using mirror mode. The primary_key field contains the row’s primary key value when available.

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

Troubleshooting

Connection failed

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

Authentication failed (401/403)

Verify the Authorization header value is correct. Ensure the token or API key has not expired. Check the endpoint’s authentication requirements.

Invalid URL

The webhook URL must start with http:// or https://. Relative URLs and other protocols are not supported.

Endpoint returning 500 errors

Server errors cause Zeotap to retry with exponential backoff. If errors persist, check the endpoint’s logs for the root cause. Ensure the endpoint can handle the JSON payload format.

Timeout

Zeotap has a default request timeout. For slow endpoints, ensure the server responds within the timeout window. Long-running processing should be handled asynchronously by the endpoint.

WebflowWhatsApp