Grove Documentation

Webhook Event Handling

Receive webhook events from external providers (Stripe, GitHub, Slack, GitLab) and route them to workflows. Grove handles signature verification, event parsing, and routing automatically.

Prerequisites: Webhooks, Workflows. What you'll learn: How to receive, verify, and process webhook events.

The Pattern

  1. Declare a webhook with provider and event mappings
  2. Events route to workflows or activities
  3. Grove handles signature verification using provider-specific algorithms

Webhook Declaration

webhook stripe "payments" {
  secret: "stripe_webhook_secret"

  on invoice.paid -> billing.process_invoice
  on charge.failed -> billing.handle_failed_charge
  on customer.created -> customers.sync_customer
}

Provider Support

ProviderSignature AlgorithmChallenge-Response
stripeHMAC-SHA256 (Stripe-Signature header)No
githubHMAC-SHA256 (X-Hub-Signature-256 header)No
slackHMAC-SHA256 (X-Slack-Signature header)Yes (url_verification)
gitlabToken match (X-Gitlab-Token header)No

Catch-All Events

Use * to route all events from a provider:

webhook github "repo-events" {
  secret: "github_webhook_secret"

  on push -> ci.trigger_build
  on pull_request -> ci.handle_pr
  on * -> audit.log_github_event
}

The catch-all * fires for any event not matched by a specific handler.

Processing Webhook Data

The target workflow or activity receives the webhook payload as its input:

workflow process_invoice v1 {
  node extract = extract_invoice_data v1
  node update = update_billing_record v1
  edge extract -> update
}

activity extract_invoice_data v1 {
  apply(input: Value) -> InvoiceData {
    return {
      invoice_id: input.data.object.id,
      customer_id: input.data.object.customer,
      amount: input.data.object.amount_paid,
      currency: input.data.object.currency
    }
  }
}

See Also