Connect any system with a webhook mapping

If a tool can send a webhook, a few lines of settings turn it into an event the pack agent understands. No glue code, and your app never waits for it.

A Shopify order becomes an “order ready” text

"sources": [{
  "name": "shopify", "path": "/hook/shopify",
  "auth": {"type": "hmac", "header": "X-Shopify-Hmac-Sha256", "secret": "env:SHOPIFY_WEBHOOK_SECRET", "encoding": "base64"},
  "map": {
    "event": {"from": "headers.x-shopify-topic", "values": {"orders/fulfilled": "order.ready"}},
    "id": "headers.x-shopify-webhook-id",
    "customer.name": "payload.customer.first_name", "customer.phone": "payload.customer.phone",
    "customer.sms_consent": {"from": "payload.customer.sms_marketing_consent.state", "values": {"subscribed": true}, "default": false},
    "order.number": "payload.order_number"}}]

The left side is where a value goes in the agent's event; the right side is where it comes from in the request: payload.a.b, headers.name, query.name, a constant, or a value translation. An event can be built from several fields with a template, as the GitHub mapping does. Anything the mapping does not recognise is ignored.

Ready-made mappings

sh sv-agent source add NAME with: github, gitlab, pagerduty, stripe, shopify, calendly, generic-pos.

Signed and safe

  • Auth types: HMAC (hex or base64), Stripe-style timestamped signatures, bearer token, a header holding a shared secret (GitLab), and our own signed event for your app. A source without auth is refused unless the agent is in dry-run.
  • Customers are only texted if the mapping carries a consent field you trust; otherwise staff are alerted instead.
  • Your own app needs one signed web request per event, never waits for the agent for more than two seconds, and keeps working if the agent is off.

Call any web API back

{"action": "http", "method": "GET", "url": "https://api.yourcrm.com/orders/{{order.number}}", "save_as": "crm"}

The server name must be written out; only the path, query and body can use values from the event, so a webhook can never choose where a request goes. The answer is available to later steps as {{http.crm.status}}.

Honest limits

  • You write the mapping once per tool; it is a settings file, not a product catalogue of certified integrations.
  • Tested with simulated tools: run in dry-run against yours and read the log first.

Keep reading