Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.iblueprint.ai/llms.txt

Use this file to discover all available pages before exploring further.

Webhook triggers let external services start an iBlueprint blueprint run by sending an HTTP POST request to a unique URL that iBlueprint generates for each trigger. When the request arrives, iBlueprint fires the blueprint and passes the incoming payload as input data. This lets you connect GitHub, Stripe, Slack, or any service that can send webhooks directly to your automated workflows.

​
How webhook triggers work

  1. You create a webhook trigger on a blueprint using blueprintTriggers.create.
  2. iBlueprint generates a unique webhook URL for that trigger: https://api.iblueprint.ai/webhooks/blueprint/{triggerId}.
  3. You register that URL with the external service (e.g. GitHub repository webhooks).
  4. When the external service fires an event, it sends a POST request to the URL.
  5. iBlueprint receives the request, extracts the payload, and starts executing the blueprint with the payload as inputData.

​
Retrieving the webhook URL — blueprintTriggers.getWebhookUrl

After creating a webhook trigger, fetch its URL with blueprintTriggers.getWebhookUrl. Procedure type: query (HTTP GET) Endpoint: 
GET https://api.iblueprint.ai/api/trpc/blueprintTriggers.getWebhookUrl

​
Parameters

​
json.triggerId
string
required
UUID of the webhook trigger.

​
Response

​
url
string
The full webhook URL to register with the external service.
​
secret
string
The signing secret set in config.secret when the trigger was created. null if no secret was configured.

​
Example

curl -G "https://api.iblueprint.ai/api/trpc/blueprintTriggers.getWebhookUrl" \
  --data-urlencode 'input={"json":{"triggerId":"trigger-uuid"}}' \
  -H "Authorization: Bearer YOUR_API_KEY"
Response: 
{
  "result": {
    "data": {
      "json": {
        "url": "https://api.iblueprint.ai/webhooks/blueprint/trigger-uuid",
        "secret": "whsec_my-signing-secret"
      }
    }
  }
}

​
Verifying webhook authenticity

When you create a webhook trigger with a secret in the config, iBlueprint signs each incoming webhook request. Verify the signature on your blueprint’s input side to ensure requests are genuine:
  1. Compute HMAC-SHA256(secret, raw_request_body).
  2. Compare the result to the X-Webhook-Signature header sent with the request.
  3. Reject requests where the signatures do not match.
import { createHmac, timingSafeEqual } from 'crypto';

function verifyWebhookSignature(body, signature, secret) {
  const expected = createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}
Always use a constant-time comparison function (timingSafeEqual) to compare signatures. String equality (===) is vulnerable to timing attacks.

​
Manually firing a trigger — blueprintTriggers.fire

Use blueprintTriggers.fire to invoke any trigger programmatically, regardless of type. This is useful for testing a webhook trigger without waiting for an external service event. Procedure type: mutation (HTTP POST) Endpoint: 
POST https://api.iblueprint.ai/api/trpc/blueprintTriggers.fire
Content-Type: application/json

​
Parameters

​
json.triggerId
string
required
UUID of the trigger to fire.
​
json.inputData
object
Key-value map of data to pass to the blueprint as if it came from the external source. Defaults to {}.

​
Example

curl -X POST "https://api.iblueprint.ai/api/trpc/blueprintTriggers.fire" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "json": {
      "triggerId": "trigger-uuid",
      "inputData": {
        "action": "opened",
        "pull_request": {
          "title": "Add dark mode support",
          "number": 42,
          "body": "This PR adds dark mode."
        },
        "repository": {
          "full_name": "acme/webapp"
        }
      }
    }
  }'

​
Example: GitHub webhook → iBlueprint blueprint

This walkthrough connects a GitHub repository’s pull request events to an iBlueprint blueprint that auto-labels and summarizes PRs.

​
Step 1 — Create a webhook trigger

curl -X POST "https://api.iblueprint.ai/api/trpc/blueprintTriggers.create" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "json": {
      "blueprintId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "triggerType": "webhook",
      "config": { "secret": "gh-webhook-secret-123" }
    }
  }'

​
Step 2 — Get the webhook URL

curl -G "https://api.iblueprint.ai/api/trpc/blueprintTriggers.getWebhookUrl" \
  --data-urlencode 'input={"json":{"triggerId":"<trigger-id-from-step-1>"}}' \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Step 3 — Register the URL in GitHub

In your GitHub repository, go to Settings → Webhooks → Add webhook:
  • Payload URL: the URL returned in step 2
  • Content type: application/json
  • Secret: gh-webhook-secret-123
  • Events: Select “Pull requests”

​
Step 4 — Blueprint receives the payload

When a pull request is opened, GitHub sends the event payload to iBlueprint. Your blueprint receives the raw payload in inputData and can reference fields like inputData.pull_request.title in node configurations.