Inbound Webhooks

Inbound webhooks let external services create records in a WorkApps app by POSTing JSON to a unique token-authenticated URL. The URL is generated when an admin creates an inbound webhook from the app's Webhooks page.

Note: Inbound webhooks are the one place you call the Data API directly — no SDK is needed because the caller is an external service, not your app's JavaScript.

Endpoint

1POST /api/workapps/v1/incoming/{token}

The {token} is the full plaintext token shown in the WorkApps dashboard when you create the webhook. No X-WorkApps-AppId header or session cookie is needed — the token identifies both the app and the target entity.

Max body size: 256 KB.

Idempotency

Include an X-Idempotency-Key header (max 255 characters) to prevent duplicate records from replayed or retried requests. WorkApps caches the response for 24 hours — any repeat request with the same key and webhook returns the original response (with an X-Idempotent-Replayed: true header) without creating a second record.

If omitted, every request creates a new record.

Request

1POST /api/workapps/v1/incoming/wh_01JA...2Content-Type: application/json3X-Idempotency-Key: my-unique-key-12345{6  "name": "Alice",7  "email": "[email protected]",8  "source": "contact-form"9}

Keys are mapped to entity field keys according to the webhook's field mapping (if configured). Unmapped keys are passed through directly. Keys that do not match any entity field are silently dropped.

Response

201 Created:

1{2  "data": {3    "record_id": "01JQRECORD00000000000000"4  }5}

Error Responses

Validation error example:

1{2  "error": {3    "code": "VALIDATION_FAILED",4    "message": "The payload failed validation.",5    "details": {6      "name": ["The name field is required."]7    }8  }9}

Quota exceeded example:

1{2  "error": {3    "code": "ERROR",4    "message": "Webhook processing failed.",5    "details": {6      "_general": ["Record count quota exceeded."]7    }8  }9}

Loop Prevention

Important: If your app uses both inbound and outbound webhooks, loop prevention is critical. Without it, a record created by an inbound webhook fires the record.created event, which triggers an outbound webhook, which may POST back to the inbound URL — creating an infinite loop.

If the request contains an X-WorkApps-Webhook-Id header (set automatically on all outbound webhook deliveries), the record.created event is not re-dispatched. This prevents outbound → inbound → outbound infinite loops when the same app has both inbound and outbound webhooks configured.

For outbound webhook configuration, see your app's Webhooks settings in the WorkApps dashboard.

Field Mapping

When creating an inbound webhook in the dashboard, you can configure a field mapping to translate incoming key names to your entity's field keys. For example, map "email_address" to "contact_email". Unmapped keys are passed through as-is.