> ## 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: receive events and fire blueprints
> Set up iBlueprint webhook triggers, retrieve the generated URL, verify payload signatures, manually fire triggers for testing, and connect external services like GitHub.
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
UUID of the webhook trigger.
### Response
The full webhook URL to register with the external service.
The signing secret set in `config.secret` when the trigger was created. `null` if no secret was configured.
### Example
```bash theme={null}
curl -G "https://api.iblueprint.ai/api/trpc/blueprintTriggers.getWebhookUrl" \
--data-urlencode 'input={"json":{"triggerId":"trigger-uuid"}}' \
-H "Authorization: Bearer YOUR_API_KEY"
```
Response:
```json theme={null}
{
"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.
```javascript theme={null}
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
UUID of the trigger to fire.
Key-value map of data to pass to the blueprint as if it came from the external source. Defaults to `{}`.
### Example
```bash curl theme={null}
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"
}
}
}
}'
```
```javascript JavaScript theme={null}
const response = await fetch(
'https://api.iblueprint.ai/api/trpc/blueprintTriggers.fire',
{
method: 'POST',
headers: {
Authorization: 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({
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' },
},
},
}),
}
);
const { result } = await response.json();
console.log('Trigger fired:', result.data.json);
```
## 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
```bash theme={null}
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
```bash theme={null}
curl -G "https://api.iblueprint.ai/api/trpc/blueprintTriggers.getWebhookUrl" \
--data-urlencode 'input={"json":{"triggerId":""}}' \
-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.