Docs · Events

Webhooks

Every change your agent needs to know about is an event. Grosso POSTs it to your endpoint, signed, and retries for about three days until you answer 2xx.

01 — Register

Register an endpoint

Endpoints are per mode. A test endpoint only ever receives test events.

POST /v1/webhook_endpointscURL

curl https://pay.grosso.ai/v1/webhook_endpoints \
  -H "Authorization: Bearer $GROSSO_API_KEY" \
  -H "idempotency-key: hook_prod_1" \
  -d '{ "url": "https://agent.example.com/grosso",
        "enabled_events": ["payment_request.paid",
                           "refund.succeeded"] }'

02 — Verify

Verify signatures

The grosso-signature header carries a timestamp and an HMAC-SHA256 of <t>.<raw body> keyed with your endpoint secret.

grosso-signatureHEADER

grosso-signature: t=1793125652,v1=5f2b9c0e7d1a…

Verify against the raw body

Parse JSON after verifying. Re-serialising the body changes the bytes and breaks the signature.

03 — Retries

Retries

A non-2xx answer or a 10-second timeout schedules the next attempt. After the last one, the delivery is marked failed; replay it with POST /v1/webhook_endpoints/:id/replay.

Attempt 1 after 0
Attempt 2 after 1m
Attempt 3 after 5m
Attempt 4 after 30m
Attempt 5 after 1h
Attempt 6 after 3h
Attempt 7 after 6h
Attempt 8 after 12h
Attempt 9 after 12h
Attempt 10 after 12h
Attempt 11 after 12h
Attempt 12 after 12h

12 attempts across about three days.

04 — Event types

Event types

Event	When
payment_request.created	A request was created and is open.
payment_request.paid	The payer paid. Tell the human it’s done.
payment_request.paid_after_close	Paid after it expired or was canceled. The money stays with the payee; decide whether to refund.
payment_request.refunded	Fully or partially refunded.
refund.pending_approval	An agent asked; waiting on the owner.
refund.approved · refund.rejected	The owner said yes, or no. An approved refund goes to Stripe next.
refund.succeeded · refund.failed	Stripe’s final answer.
dispute.updated · dispute.closed	A payer disputed a charge, or the dispute was decided.
payee.invited · payee.updated	A payee was invited, or its metadata changed.
payee.paused	The payee can’t take payments; its open requests were canceled.
payee.unpaused	The pause was lifted; the payee’s status is back.
account.suspended	Your account was suspended; payees are paused and open requests canceled.
account.identity_verification.updated	Your identity check moved forward.