Sending Marshal a Webhook

Marshal can take an inbound webhook from any system you own — no integration has to be written for it first. You get a URL and a signing secret, your system signs each request, and a deputy mission fires on the events you pick.

This page is the contract. Hand it to whoever writes the sending side.

Getting a URL

An org admin enables it once, in Settings → Webhooks:

1. Install the generic-hmac-webhook package from the Marketplace.
2. Press Connect on its row.
3. Copy the delivery URL and the signing secret.

The URL looks like this, and the token in it is the only thing that identifies your connection — treat it as a credential:

POST https://hooks.marshal.codes/webhook/conn/<token>

Signing a request

Every request carries three headers.

Two rules decide whether your integration works:

• Sign the raw bytes you send. Not a re-serialized copy. If your HTTP client re-encodes the body after you sign it, the signature will not match.
• Sign the timestamp with it. The string is the timestamp, a literal ., then the body. Marshal rejects a request whose X-Timestamp is more than five minutes from its own clock, in either direction, so a request captured off the wire cannot be replayed later.

URL="https://hooks.marshal.codes/webhook/conn/REPLACE_WITH_TOKEN"
SECRET="REPLACE_WITH_SECRET"
BODY='{"invoice":"inv_123","amount":4200}'
TS=$(date +%s)
 
SIG=$(printf '%s.%s' "$TS" "$BODY" \
  | openssl dgst -sha256 -hmac "$SECRET" -hex \
  | sed 's/^.* //')
 
curl -sS -X POST "$URL" \
  -H "Content-Type: application/json" \
  -H "X-Timestamp: $TS" \
  -H "X-Signature: $SIG" \
  -H "X-Event-Type: invoice.paid" \
  --data-raw "$BODY"

import hashlib, hmac, json, time, requests
 
URL = "https://hooks.marshal.codes/webhook/conn/REPLACE_WITH_TOKEN"
SECRET = "REPLACE_WITH_SECRET"
 
# Serialize ONCE, sign those exact bytes, send those exact bytes.
body = json.dumps({"invoice": "inv_123", "amount": 4200}).encode()
ts = str(int(time.time()))
sig = hmac.new(SECRET.encode(), ts.encode() + b"." + body, hashlib.sha256).hexdigest()
 
requests.post(
    URL,
    data=body,
    headers={
        "Content-Type": "application/json",
        "X-Timestamp": ts,
        "X-Signature": sig,
        "X-Event-Type": "invoice.paid",
    },
    timeout=10,
)

import { createHmac } from 'node:crypto'
 
const URL = 'https://hooks.marshal.codes/webhook/conn/REPLACE_WITH_TOKEN'
const SECRET = 'REPLACE_WITH_SECRET'
 
const body = JSON.stringify({ invoice: 'inv_123', amount: 4200 })
const ts = Math.floor(Date.now() / 1000).toString()
const sig = createHmac('sha256', SECRET).update(`${ts}.${body}`).digest('hex')
 
await fetch(URL, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Timestamp': ts,
    'X-Signature': sig,
    'X-Event-Type': 'invoice.paid',
  },
  body,
})

import (
	"bytes"
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"fmt"
	"net/http"
	"strconv"
	"time"
)
 
const (
	url    = "https://hooks.marshal.codes/webhook/conn/REPLACE_WITH_TOKEN"
	secret = "REPLACE_WITH_SECRET"
)
 
func postEvent() error {
	body := []byte(`{"invoice":"inv_123","amount":4200}`)
	ts := strconv.FormatInt(time.Now().Unix(), 10)
 
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write([]byte(ts))
	mac.Write([]byte{'.'})
	mac.Write(body)
	sig := hex.EncodeToString(mac.Sum(nil))
 
	req, _ := http.NewRequest(http.MethodPost, url, bytes.NewReader(body))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("X-Timestamp", ts)
	req.Header.Set("X-Signature", sig)
	req.Header.Set("X-Event-Type", "invoice.paid")
 
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		return err
	}
	defer resp.Body.Close()
	if resp.StatusCode != http.StatusAccepted {
		return fmt.Errorf("marshal webhook: %s", resp.Status)
	}
	return nil
}

Already sending webhooks in another format?

If the system that will post to Marshal already emits signed webhooks, it probably speaks one of these. Choose that format when you create the endpoint and change nothing on the sending side.

An endpoint verifies with exactly one of these — the one you chose. A request signed correctly in a different format is refused, because an endpoint that accepted any of them would only ever be as strong as the weakest one a sender happened to pick.

Two notes for the formats that are somebody else’s specification. Standard Webhooks secrets are written whsec_ followed by base64, and the signature is computed over the decoded bytes — which is what the official SDKs do, so if you use one it will work unchanged. Stripe’s header may carry several v1 signatures while a secret is rolling; any one of them matching is accepted, and the v0 it sends for test events is ignored.

Naming your events

X-Event-Type is the name a deputy trigger binds to. Pick names with a family prefix — invoice.paid, invoice.refunded, deal.created — and a trigger can bind to one (invoice.paid), to the family (invoice.*), or to everything (*).

Send no header and every delivery arrives as *. That still works: the trigger binds to * and its condition sorts out what the event was. But then every binding wakes on every delivery, so the header is worth setting.

What comes back

Accepted and refused requests both show up under Settings → Webhooks, in one timeline, newest first. A refused one says which of three things went wrong — so the 404 your sender received stays uninformative, while the person who owns the endpoint can see the real reason:

The body of a refused request is not kept unless the endpoint’s owner turns that on, because a refused request is unverified: it is whatever anybody who found the URL chose to post. Turn it on while you are getting set up, and off again afterwards.

Older refusals are dropped once an endpoint has stored 50 of them. The timeline says so when that has happened, so the oldest one you can see is never mistaken for the first one that happened.

Rotating your secret

The endpoint’s owner can issue a new signing secret without changing the URL, from Settings → Webhooks. The old secret keeps working for 24 hours, so you can deploy the new one without losing a delivery: during that window either secret verifies.

If a secret has leaked, there is a second option that skips the overlap entirely. It stops the old secret immediately — which means your sender fails until it has the new one. That is the point.

Rotating twice inside the window retires the older secret at once. There is only ever one retiring secret, never a chain.

Changing your format

An endpoint’s format can be changed later, again without a new URL or a new secret — useful if you move your sender to a different library. Moving to Body only removes replay protection, and nothing on your side signals that it happened, so Marshal warns before confirming and records the change in the audit trail.

Reaching a deputy

A delivery on its own does nothing until a mission is bound to it. In the mission’s Triggers, add one with:

• Source — generic-hmac-webhook
• Event — the X-Event-Type you send, or a family, or *
• Condition (optional) — a CEL expression over the payload, e.g. event.amount > 1000
• Inputs — which fields of the payload reach the agent. Only what you map is passed on.

Two deliveries carrying the same id, event_id, delivery_id, webhookId or eventId fire the trigger once, so a retry on your side is safe.