Skip to docs content
Browse documentation
On this page

Purchase thanks

A worked event example: a verified purchase becomes a fact your factory already knows, and a package drafts a thank-you without anyone typing. Load this when someone asks how to react to an event a package you own already emitted.

Purchase thanks

A purchase notification is a useful example of package webhooks and events. The package code in this guide is a pattern for you to build; Minion does not ship a Stripe or Gmail package.

Choose what happens after checkout

One package can receive a Stripe webhook, verify the event with Stripe, and handle the purchase. Or, one package can verify the payment and emit an organization-owned event for another package to handle.

Use the webhook signing secret from Stripe and Minion's HMAC webhook verification. Treat the posted event body as untrusted until the handler verifies the event with Stripe. Avoid recording card, customer, or receipt data in logs.

Gmail drafts need broad permission

To create a Gmail draft, the Google integration must have Gmail API access. Minion's default Google scopes do not include Gmail. Google's gmail.compose scope can manage drafts and send email; it does not enforce a drafts-only permission. See Google's Gmail API scope list .

A package can be written to create a draft and never call a send method, but Minion cannot restrict that OAuth grant to draft creation. Package versions and integration host restrictions do not prevent other code that can use the same integration from sending mail. Connect a narrowly scoped integration only when the owner accepts that permission. If the workflow must not send Gmail, use another notification path instead.

One package: verify and handle the webhook

Declare an HMAC-verified webhook in package.json#minion.webhooks. Minion runs the matching package export after it verifies the request.

{
  "name": "@your-team/purchase-thanks",
  "exports": { "./stripe": "./src/stripe.ts" },
  "minion": {
    "webhooks": [{
      "name": "stripe-checkout",
      "export": "./stripe",
      "responseMode": "ack",
      "verification": {
        "type": "hmac-sha256",
        "header": "stripe-signature",
        "secretName": "stripeWebhookSecret",
        "encoding": "hex"
      }
    }]
  }
}

After the handler verifies the event, it can fetch the checkout from Stripe and then perform the action you chose. Keep the webhook response quick; stage longer work in a workflow.

Two packages: emit an owned event

After one package verifies a payment, it can emit a topic declared in its manifest. A second package can subscribe to that topic. events.dispatch is available in saved package code, not ad hoc execute.

await minion.events.dispatch({
  topic: '@your-team/purchase.completed',
  idempotencyKey: `stripe:checkout:${eventId}`,
  payload: { eventId, product: 'Example product' },
})

The emitting package declares the topic in package.json#minion.emits. The handler package declares a matching package.json#minion.subscriptions entry. A delivery is deduplicated by idempotencyKey; the JSON payload limit is 64 KiB.

Test the handler

Owners and admins can smoke-test a webhook export with minion.webhooks.dispatchSynthetic. It skips the external URL and signature check, but it runs real code with real side effects. For an event subscription, minion.events.dispatchSynthetic also runs the real handler; it does not emit downstream events.

Use only test purchase data. Verify the webhook or event delivery and the resulting run before connecting a live Stripe endpoint.

Related