How to integrate Unify with Databricks
To integrate Unify with Databricks for storage, POST prospect JSON to a custom receiver that persists an ingestion job. A worker submits a parameterized write to a SQL warehouse using the Statement Execution API, follows the statement ID, and verifies its final state. HTTP acceptance alone does not prove the write succeeded.[1][3]
- Connection
- Via webhook + endpoint
- Data storage
- Tool
- Databricks
- Custom ingestion receiver
- Data flow
- Unify → Vercel Function → Databricks
- JSON payload
At a glance
- Define the target table and the prospect properties allowed into it
- Save a job independently of warehouse execution
- Track the statement ID to a final execution state
When this workflow makes sense
Start with the decision your team needs to make, then choose the connection that supports it.
A lakehouse handoff should preserve both the incoming facts and the outcome of the write. The API can accept a statement that later fails, so an ingestion record needs a lifecycle beyond received. Define the destination schema, how to recognize a repeated handoff, and who resolves records that fail validation or execution.
A good fit when
Teams with a Databricks analytical workload, a suitable SQL warehouse, and an owner for the ingestion process.
Reconsider the plan when
Avoid tying the Play’s response to warehouse startup or a long SQL operation. If the use case is an immediate rep task, a storage feed may not be the first integration to build.
Design the handoff
Use this framework to agree on the input, the next action, and who owns the result.
Suggested workflow design, based on the documented capabilities below.
| Stage | Decision to make |
|---|---|
| Contract | Define the target table and the prospect properties allowed into it |
| Intake | Save a job independently of warehouse execution |
| State | Track the statement ID to a final execution state |
| Reconcile | Compare successful jobs with the records consumers can query |
Explore the scenarios
Choose the situation that fits your team and work through the proposed plan.
Open a scenario to explore its plan. Checklists track your selections in this page only.
Add selected prospects to a data product
A reporting table needs a curated subset of prospect facts.
Agree the table meaning and consumers before connecting the Play.
- Define the input contract and destination
- Submit a controlled job through the worker
- Inspect both statement state and stored values
Separate acceptance from SQL failure
The endpoint accepts a record whose write fails later.
An accepted request should stay traceable until success or an owned failure.
- Send a controlled invalid value
- Inspect the statement’s final error
- Correct the input and replay under the chosen identity rule
Illustrative workflow, not a preconfigured automation. Complete these checks in your own account.
Define success before launch
Inspect the data and the intended outcome separately. Connection status is only the first check.
Expected, not tested
The persisted ingestion job reaches SUCCEEDED and the intended table contains the expected prospect values.
Inspect status.state as well as the HTTP status, then read the expected destination record. Request acceptance, a statement ID, and SQL success are distinct checkpoints.
Documentation-based reference. This workflow has not been tested end to end. Use a record or event you control before enabling live activity.
Questions answered
Common decisions when connecting Unify and Databricks.
Does Unify send the webhook directly to a Databricks table?
This design sends JSON to an application receiver. Its worker transforms the data into a Statement Execution API request for a chosen SQL warehouse.[3]
Why is asynchronous execution useful here?
The sender expects a response within 8 seconds. Persisting a job and tracking the database operation separately avoids coupling webhook acknowledgement to warehouse execution time.[2]
What does wait_timeout: "0s" do?
It requests asynchronous execution and returns a statement ID and current state rather than waiting for the final result. The worker can then poll for completion.[3]
Can a 200 response contain a failed SQL statement?
Yes. Inspect status.state and the returned error instead of treating HTTP 200 as evidence of a successful write.[3]
Should I put a service principal secret in the prospect body?
Keep the machine-to-machine credentials in the worker environment. Use a separate receiver credential for the Unify request.[4]
Limits & decisions
Check these boundaries before designing a live workflow around the connection.
- Requires a custom intake service and background worker
- Service principal permissions must cover both warehouse use and the intended table operation
- A statement ID does not guarantee a stored record
- Replay behavior is an application decision; this article does not promise automatic event deduplication
- No live Databricks statement or table write has been executed
What the connection supports
Understand the connection, the data involved, and the behavior that matters for a Unify + Databricks workflow.
POST / JSON to a receiver, then SQL Statement Execution
| Decision | What to know |
|---|---|
| Submission | POST /api/2.0/sql/statements executes a statement on a SQL warehouse[3] |
| Parameters | Named parameters carry values separately from SQL text[3] |
| Asynchronous mode | wait_timeout: "0s" returns a statement ID for polling[3] |
| Final state | Inspect SUCCEEDED, FAILED, or CANCELED instead of HTTP status alone[3] |
| Machine identity | OAuth machine-to-machine authentication uses a service principal[4] |
Technical setup reference
References and requirements for the Databricks connection.
Connection requirements and setup checklist
Before connecting
- A Unify Play with a Webhook action
- An HTTPS receiver, durable job storage, and a worker maintained by your team
- A destination table and an agreed definition of record identity
- A database service identity with only the required permissions
- A Databricks SQL warehouse, target catalog and schema, and permission to write the table
- A service principal and a configured machine-to-machine authentication path
Configure service authentication
Give the worker a service principal with the necessary warehouse and data permissions. Use the documented OAuth machine-to-machine setup and keep credential renewal in the worker environment.[4]
Check the execution state
Poll the statement endpoint using its ID until a final state is reported. Treat SUCCEEDED as the execution-success state and handle FAILED or CANCELED explicitly. A 200 HTTP response can still contain a failed statement state.[3]
Request configuration
- Method
POST- URL pattern
https://YOUR_APP.vercel.app/api/unify-to-databricks- Headers
Content-Type: application/jsonX-Unify-Webhook-Key: YOUR_WEBHOOK_SECRET- Authentication
- Suggested receiver authentication: implement X-Unify-Webhook-Key validation in your own HTTPS service. Store its expected value server-side and configure Unify API Key (Header) with the matching secret. This is an application contract you implement, not a built-in database header. Keep database credentials and token renewal in the receiving service.
Choose JSON as the body format. Unify sets Content-Type automatically. The receiver must respond within Unify’s 8-second timeout; request responses are not passed to later Play steps.[2]
Replace URL placeholders with the actual receiver URL from your account or deployed application. These example URLs are not working endpoints.
Example handoff payload
Start with a fictional prospect. Validate the resolved values before using a real record.
Inspect the sample payload and field mapping
{
"event": "prospect_handoff",
"prospect_name": "Alex Morgan",
"prospect_email": "alex@example.com",
"company_name": "Example Company",
"company_domain": "example.com"
}Fictional data. Replace sample values before using a real Play.
This sample is the receiver input. It is not the complete Databricks Statement Execution API request. Use the field mapping to distinguish record data from fixed settings. Select available fields in your Play and inspect Expand preview; do not replace configuration values with prospect data.[2]
| Payload field | Value to send |
|---|---|
event | A fixed label you choose for this workflow |
prospect_name | Use {{ person.first_name }} and {{ person.last_name }} for the prospect name |
prospect_email | Use {{ person.email }}; decide how to handle missing values |
company_name | Use {{ company.name }} |
company_domain | Use {{ company.domain }} |
The receiver accepts the fictional prospect JSON. The worker maps validated values to named SQL parameters in a separate Statement Execution API request. Keep warehouse_id and target identifiers under application control.
Troubleshooting
Start with the stage where the expected data or action stops appearing.
HTTP 200 is returned but the write failed
Read status.state and the accompanying error. The Statement Execution API can return HTTP 200 with FAILED for an execution error.[3]
Sources & review
Official documentation reviewed on September 15, 2026.
Technical claims link to primary documentation from Unify and the destination tool. Scenarios, field choices, and recovery plans are editorial implementation examples. Documentation review is separate from execution testing.
Documentation reviewed; end-to-end execution not tested. No named technical reviewer has signed off on these articles yet.
Content updated: . Report a correction to Unify with the tool name, source URL, and behavior you observed.
Keep exploring
