Skip to content

Generic Webhook Integration

Receive events from any external service with configurable HMAC signature verification. This integration allows you to trigger Raikoo workflows from services like GitHub, Stripe, Shopify, and custom applications.

What You Can Build

  • CI/CD automation: Trigger workflows when code is pushed or PRs are created
  • Payment processing: Handle Stripe payment events and update your systems
  • E-commerce automation: Process Shopify orders and inventory updates
  • Custom integrations: Connect any service that supports webhooks

Prerequisites

Before setting up webhook integration, you will need:

  • The external service configured to send webhooks
  • The webhook secret or signing key from the external service (if using signature verification)
  • Admin access to your Raikoo organization

Setup Steps

Step 1: Create a Connection in Raikoo

  1. Navigate to your organization in Raikoo
  2. Click Connections in the left navigation
  3. Click Create Connection
  4. Configure the connection:
  5. Name: Give it a descriptive name (e.g., "GitHub Webhooks")
  6. Description: Optional description
  7. Platform: Select Generic Webhook
  8. Go to the Credentials tab
  9. Select a Webhook Preset or configure custom settings:

Available Presets

Preset HMAC Header Algorithm Description
GitHub x-hub-signature-256 SHA-256 GitHub webhook events (push, PR, issues)
Stripe stripe-signature SHA-256 Stripe payment and subscription events
Zapier x-zapier-signature SHA-256 Zapier automation webhooks
Linear linear-signature SHA-256 Linear issue and project events
Slack x-slack-signature SHA-256 Slack Events API webhooks
Shopify x-shopify-hmac-sha256 SHA-256 Shopify store events
Custom Configurable Configurable Custom webhook format
  1. If using the Custom preset, configure:
  2. HMAC Header: The HTTP header containing the signature
  3. HMAC Algorithm: SHA-256 or SHA-1
  4. Webhook Secret: The secret key for signature verification
  5. Click Save

Step 2: Create an Integration (Trigger)

  1. Navigate to Integrations in the left navigation
  2. Click Create Trigger
  3. Configure the trigger:
  4. Name: A descriptive name (e.g., "GitHub PR Handler")
  5. Description: What this trigger does
  6. External Connection: Select the webhook connection you created
  7. Go to the Execution tab:
  8. Execution Mode: Choose "Workflow" (recommended for webhooks)
  9. Project: Select the project containing your workflow
  10. Workflow: Select the workflow to execute
  11. Authentication Mode: Configure how executions are authenticated
  12. Click Save

Step 3: Configure the External Service

  1. In Raikoo, go to the Webhook tab of your trigger
  2. Copy the Webhook URL and Webhook Secret
  3. In your external service (GitHub, Stripe, etc.):
  4. Navigate to webhook settings
  5. Add a new webhook
  6. Paste the Raikoo webhook URL
  7. Enter the secret (if prompted)
  8. Select the events you want to receive
  9. Save the webhook configuration

Platform-Specific Setup

GitHub Webhooks

  1. Go to your repository or organization settings
  2. Click Webhooks > Add webhook
  3. Configure:
  4. Payload URL: Your Raikoo webhook URL
  5. Content type: application/json
  6. Secret: Your webhook secret from Raikoo
  7. SSL verification: Enable
  8. Events: Select which events to receive
  9. Click Add webhook

Stripe Webhooks

  1. Go to the Stripe Dashboard
  2. Click Add endpoint
  3. Configure:
  4. Endpoint URL: Your Raikoo webhook URL
  5. Events: Select events to receive
  6. After creation, reveal and copy the Signing secret
  7. Add the signing secret to your Raikoo connection

Shopify Webhooks

  1. Go to your Shopify admin panel
  2. Navigate to Settings > Notifications > Webhooks
  3. Click Create webhook
  4. Configure:
  5. Event: Select the event type
  6. Format: JSON
  7. URL: Your Raikoo webhook URL
  8. Note the webhook secret shown (use it in Raikoo)

Webhook Payload in Workflows

When a webhook triggers a workflow, the entire payload is available:

Parameter Description
TRIGGER_PLATFORM Always "webhook"
TRIGGER_CONNECTION_ID The connection ID

Additionally, any parameters you send in your webhook payload's parameters object are available directly:

Accessing Payload Data

In your webhook request, send parameters in a structured format:

{
  "parameters": {
    "action": "opened",
    "repository": "my-repo",
    "title": "Fix bug"
  }
}

These are then available in your workflow:

{{WorkflowParameters.action}}
{{WorkflowParameters.repository}}
{{WorkflowParameters.title}}

Signature Verification

Raikoo uses timing-safe HMAC verification to validate webhook signatures:

  1. Extract Signature: The signature is read from the configured header
  2. Compute Expected: HMAC is computed using your secret and the raw request body
  3. Compare: Signatures are compared using timing-safe comparison to prevent attacks
  4. Validate: Requests with invalid signatures are rejected

Supported Signature Formats

Format Example Notes
Prefixed sha256=abc123... GitHub style
Raw abc123... Plain hex hash
Versioned v1=abc123... Stripe style

Testing Webhooks

Without Signature Verification

For development, you can leave the webhook secret empty. This allows any request to be processed without verification.

Warning: Only do this in development environments. Always use signature verification in production.

Using ngrok for Local Testing

  1. Install ngrok
  2. Start your local Raikoo instance
  3. Run: ngrok http 3000
  4. Use the ngrok URL as your webhook endpoint
  5. Test webhooks from your external service

Manual Testing with curl

# Without signature
curl -X POST https://your-raikoo-domain/api/triggers/{webhookId} \
  -H "Content-Type: application/json" \
  -d '{"event": "test", "data": {"message": "Hello"}}'

# With signature (GitHub style)
curl -X POST https://your-raikoo-domain/api/triggers/{webhookId} \
  -H "Content-Type: application/json" \
  -H "x-hub-signature-256: sha256=<computed-signature>" \
  -d '{"event": "test"}'

Troubleshooting

Webhook Not Triggering

  1. Verify the webhook URL is correct in the external service
  2. Check that your trigger is set to Active
  3. Review webhook delivery logs in the external service
  4. Ensure the external service can reach your Raikoo instance

Signature Verification Failed

  1. Verify the correct preset is selected for your service
  2. Check that the webhook secret matches in both Raikoo and the external service
  3. Ensure the secret does not have extra whitespace
  4. For custom setups, verify the HMAC header name is correct

Payload Not Parsing

  1. Ensure the external service sends Content-Type: application/json
  2. Check that the payload is valid JSON
  3. Verify the payload path (if configured) exists in the request

Workflows Not Executing

  1. Check that a workflow is selected in the trigger's Execution tab
  2. Verify the workflow has a compatible starting point
  3. Review workflow execution logs for errors

Best Practices

  • Always use signature verification in production environments
  • Use dedicated secrets: Generate unique secrets for each webhook source
  • Monitor webhook deliveries: Check external service logs for failures
  • Implement idempotency: Design workflows to handle duplicate webhooks safely
  • Keep secrets secure: Store webhook secrets only in Raikoo, not in code

Payload Path Extraction

For webhooks that nest the actual payload inside a wrapper, you can specify a Payload Path:

// Original webhook payload
{
  "wrapper": {
    "metadata": { "timestamp": "..." },
    "data": {
      "event": "order.created",
      "order": { ... }
    }
  }
}

// With payloadPath = "wrapper.data"
// Your workflow receives:
{
  "event": "order.created",
  "order": { ... }
}

Configure this in the connection's Credentials tab under advanced settings.

Next Steps