Webhooks let you trigger Definite blocks from external systems with a simple HTTPS POST. Send JSON to our endpoint, and Definite will execute your block immediately with your data and environment variables. This enables real-time pipelines for events like signups, payments, orders, alerts, and more.

​
How it works (at a glance)

1

Send a POST to the Definite webhook endpoint with your block ID and JSON payload.
2

Authenticate using a bearer token or request token.
3

Inject & merge: Your JSON is injected as WEBHOOK_DATA and any env vars are merged into the block’s runtime.
4

Execute: Definite runs the block (asynchronously under the hood) with the provided data.
5

Respond: You get a response with execution metadata and (when applicable) results or error details.

​
Endpoint

POST /v2/webhook/blocks/{block_id}/execute
Where {block_id} is the UUID of the block to execute.

​
Authentication

You can authenticate in either of the following ways:
  1. Bearer token (recommended) 
    Authorization: Bearer YOUR_API_KEY
  2. Request token in body 
    {
  "token": "YOUR_API_TOKEN",
  ...
}
    API key format: {user_id}-{api_key_suffix}

​
Request Body

{
  "token": "string (required if not using Authorization header)",
  "data": {                       // Optional: Arbitrary JSON passed to your block
    "event_type": "user_created",
    "user_id": "123"
  },
  "environment_variables": {      // Optional: Runtime env vars for the block
    "API_KEY": "secret_key",
    "DEBUG_MODE": "true"
  },
  "python": {                     // Optional: Language-specific overrides
    "environment_variables": {
      "PYTHON_SPECIFIC": "value"
    }
  }
}

​
Data injection & merging

  • The data object is injected as a JSON string into the WEBHOOK_DATA environment variable.
  • Environment variables are merged with the block’s existing configuration (see precedence below).

​
Environment Variable Precedence

When runtime variables are merged, later items override earlier ones:
  1. Block’s saved environment variables
  2. WEBHOOK_DATA (built from request data)
  3. environment_variables (top-level in the request)
  4. python.environment_variables (language-specific overrides)

​
Execution & Response

Success 
{
  "success": true,
  "execution_id": "uuid-string",  // Useful for tracing execution in Definite
  "result": { ... },              // Result payload (when applicable)
  "error": null
}
Error 
{
  "success": false,
  "execution_id": null,
  "result": null,
  "error": "Error description"
}
Note: Execution is asynchronous under the hood, but the HTTP response includes enough metadata for you to trace or poll results if needed.

​
Accessing webhook data inside a Python block

import os, json

# WEBHOOK_DATA is injected as a JSON string
webhook_data = json.loads(os.environ["WEBHOOK_DATA"])
event_type = webhook_data.get("event_type")

# Any environment variables you passed are available via os.environ
api_key = os.environ.get("API_KEY")

print(f"Processing {event_type} event")

​
Examples

Basic call 
curl -X POST https://api.definite.app/v2/webhook/blocks/YOUR_BLOCK_ID/execute \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "data": {
      "event_type": "user.created",
      "user_id": "123"
    }
  }'
With environment variables 
curl -X POST https://api.definite.app/v2/webhook/blocks/YOUR_BLOCK_ID/execute \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "data": {
      "event_type": "payment.succeeded",
      "provider": "stripe"
    },
    "environment_variables": {
      "API_KEY": "sk_test_123",
      "DEBUG_MODE": "true"
    }
  }'

​
Common use cases

  • Event processing: payments, signups, order lifecycle events
  • Streaming ingestion: telemetry, IoT, monitoring alerts
  • Workflow automation: trigger transformations or enrichment on external events
  • Third-party callbacks: process responses from external integrations

​
Best practices

  • Use bearer auth in the Authorization header where possible.
  • Keep payloads small and focused; put only what the block needs.
  • Include an idempotency key (e.g., in data.request_id) if your sender may retry.
  • Separate secrets from data: pass secrets via environment_variables, not in data.
  • Log execution_id from responses to trace runs in Definite.

​
Troubleshooting

  • 401 Unauthorized: Check API key format and header vs. request token usage.
  • 403 Forbidden: Ensure the API key has access to the target block.
  • 400 Bad Request: Validate JSON structure; ensure data is valid JSON if provided.
  • 5xx errors: Temporary issue—retry with exponential backoff; include an idempotency key.

​
Summary

Definite webhooks connect your external events to live data processing. Send a POST with JSON, we inject it into the block runtime, merge your environment variables, execute the block, and return execution metadata so you can trace outcomes—all with a single, simple integration.