Webhook

Overview

The Webhook events extension receives HTTP webhooks from external services such as GitHub, Stripe, Shopify, internal systems, and low-code tools. The extension parses the request, validates it when configured, and emits one or more EventEnvelopeV1 events for flows.

Setup

Configure Provider

{
  "events-webhook": {
    "enabled": true,
    "public_base_url": "https://your-domain.ngrok-free.app"
  }
}

Run Setup

gtc setup --answers answers.json ./my-bundle

Register Webhook

Use the generated webhook URL in your external service:

https://your-domain.com/v1/events/ingress/events-webhook/{tenant}/{team?}/{handler?}

Configuration Options

Option	Required	Description
`enabled`	Yes	Enable/disable provider
`public_base_url`	Yes	Public URL for webhooks
`secret_header`	No	Header name for simple signature schemes when the installed pack supports it
`secret_key`	No	Secret used for webhook validation when the installed pack supports it

Webhook URL Format

The standard Greentic event ingress route is:

POST https://your-domain.com/v1/events/ingress/{provider}/{tenant}/{team?}/{handler?}

Example:

POST https://your-domain.com/v1/events/ingress/events-webhook/demo/default/github

Some demo or app-specific packs can declare shorter routes such as /events/webhook/demo/alert. Prefer the URL printed by gtc setup or the route table for the installed pack.

Handling Webhooks

Basic Handler

name: handle_webhook
version: "1.0"

nodes:
  - id: process
    type: script
    config:
      script: |
        let data = event.payload;
        // Process webhook data
        data
    to: respond

  - id: respond
    type: http_response
    config:
      status: 200
      body:
        success: true

triggers:
  - type: event
    event_type: "order.created"
    target: process

GitHub Webhook

nodes:
  - id: check_event
    type: branch
    config:
      conditions:
        - expression: "headers['x-github-event'] == 'push'"
          to: handle_push
        - expression: "headers['x-github-event'] == 'pull_request'"
          to: handle_pr
      default: ignore

  - id: handle_push
    type: script
    config:
      script: |
        let commits = event.payload.commits;
        format!("Received {} commits", commits.len())

triggers:
  - type: event
    event_type: "github"
    target: check_event

Stripe Webhook

nodes:
  - id: handle_stripe
    type: branch
    config:
      conditions:
        - expression: "event.payload.type == 'payment_intent.succeeded'"
          to: payment_success
        - expression: "event.payload.type == 'payment_intent.failed'"
          to: payment_failed

triggers:
  - type: event
    event_type: "stripe"
    target: handle_stripe

Signature Validation

Signature configuration is extension-pack specific. Inspect the installed pack with gtc wizard --schema or run gtc setup to see the supported answers.

Common upstream schemes:

GitHub signs webhook bodies with X-Hub-Signature-256 using HMAC SHA-256 and the webhook secret.
Stripe signs events with Stripe-Signature; Stripe recommends validating against the raw request body and endpoint secret.
Twilio signs requests with X-Twilio-Signature using the account Auth Token.

For providers with official SDK signature helpers, prefer the provider’s helper when building a custom extension.

Response Handling

Immediate Response

Most webhook providers expect a quick response:

- id: ack
  type: http_response
  config:
    status: 200
  to: async_process  # Process async after responding

Async Processing

For long-running tasks, acknowledge first:

nodes:
  - id: acknowledge
    type: http_response
    config:
      status: 202
      body:
        message: "Processing"
    to: process_async

  - id: process_async
    type: async
    config:
      flow: "process_webhook_data"
      payload: "{{event.payload}}"

Testing Webhooks

Using curl

curl -X POST https://your-domain.com/v1/events/ingress/events-webhook/demo/default/test \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello from webhook"}'

Using ngrok inspector

ngrok http 8080
# Visit http://localhost:4040 to inspect requests