|
1 | 1 | --- |
2 | | -description: Create webhook triggers for a Sim Studio integration using the generic trigger builder |
| 2 | +description: Create webhook triggers for a Sim integration using the generic trigger builder |
3 | 3 | argument-hint: <service-name> |
4 | 4 | --- |
5 | 5 |
|
6 | 6 | # Add Trigger Skill |
7 | 7 |
|
8 | | -You are an expert at creating webhook triggers for Sim Studio. You understand the trigger system, the generic `buildTriggerSubBlocks` helper, and how triggers connect to blocks. |
| 8 | +You are an expert at creating webhook triggers for Sim. You understand the trigger system, the generic `buildTriggerSubBlocks` helper, and how triggers connect to blocks. |
9 | 9 |
|
10 | 10 | ## Your Task |
11 | 11 |
|
@@ -552,6 +552,53 @@ All fields automatically have: |
552 | 552 | - `mode: 'trigger'` - Only shown in trigger mode |
553 | 553 | - `condition: { field: 'selectedTriggerId', value: triggerId }` - Only shown when this trigger is selected |
554 | 554 |
|
| 555 | +## Trigger Outputs & Webhook Input Formatting |
| 556 | + |
| 557 | +### Important: Two Sources of Truth |
| 558 | + |
| 559 | +There are two related but separate concerns: |
| 560 | + |
| 561 | +1. **Trigger `outputs`** - Schema/contract defining what fields SHOULD be available. Used by UI for tag dropdown. |
| 562 | +2. **`formatWebhookInput`** - Implementation that transforms raw webhook payload into actual data. Located in `apps/sim/lib/webhooks/utils.server.ts`. |
| 563 | + |
| 564 | +**These MUST be aligned.** The fields returned by `formatWebhookInput` should match what's defined in trigger `outputs`. If they differ: |
| 565 | +- Tag dropdown shows fields that don't exist (broken variable resolution) |
| 566 | +- Or actual data has fields not shown in dropdown (users can't discover them) |
| 567 | + |
| 568 | +### When to Add a formatWebhookInput Handler |
| 569 | + |
| 570 | +- **Simple providers**: If the raw webhook payload structure already matches your outputs, you don't need a handler. The generic fallback returns `body` directly. |
| 571 | +- **Complex providers**: If you need to transform, flatten, extract nested data, compute fields, or handle conditional logic, add a handler. |
| 572 | + |
| 573 | +### Adding a Handler |
| 574 | + |
| 575 | +In `apps/sim/lib/webhooks/utils.server.ts`, add a handler block: |
| 576 | + |
| 577 | +```typescript |
| 578 | +if (foundWebhook.provider === '{service}') { |
| 579 | + // Transform raw webhook body to match trigger outputs |
| 580 | + return { |
| 581 | + eventType: body.type, |
| 582 | + resourceId: body.data?.id || '', |
| 583 | + timestamp: body.created_at, |
| 584 | + resource: body.data, |
| 585 | + } |
| 586 | +} |
| 587 | +``` |
| 588 | + |
| 589 | +**Key rules:** |
| 590 | +- Return fields that match your trigger `outputs` definition exactly |
| 591 | +- No wrapper objects like `webhook: { data: ... }` or `{service}: { ... }` |
| 592 | +- No duplication (don't spread body AND add individual fields) |
| 593 | +- Use `null` for missing optional data, not empty objects with empty strings |
| 594 | + |
| 595 | +### Verify Alignment |
| 596 | + |
| 597 | +Run the alignment checker: |
| 598 | +```bash |
| 599 | +bunx scripts/check-trigger-alignment.ts {service} |
| 600 | +``` |
| 601 | + |
555 | 602 | ## Trigger Outputs |
556 | 603 |
|
557 | 604 | Trigger outputs use the same schema as block outputs (NOT tool outputs). |
@@ -649,6 +696,11 @@ export const {service}WebhookTrigger: TriggerConfig = { |
649 | 696 | - [ ] Added `delete{Service}Webhook` function to `provider-subscriptions.ts` |
650 | 697 | - [ ] Added provider to `cleanupExternalWebhook` function |
651 | 698 |
|
| 699 | +### Webhook Input Formatting |
| 700 | +- [ ] Added handler in `apps/sim/lib/webhooks/utils.server.ts` (if custom formatting needed) |
| 701 | +- [ ] Handler returns fields matching trigger `outputs` exactly |
| 702 | +- [ ] Run `bunx scripts/check-trigger-alignment.ts {service}` to verify alignment |
| 703 | +
|
652 | 704 | ### Testing |
653 | 705 | - [ ] Run `bun run type-check` to verify no TypeScript errors |
654 | 706 | - [ ] Restart dev server to pick up new triggers |
|
0 commit comments