Webhooks

Receive a webhook event

Marfa sends this request to a webhook's url for each event it subscribes to, with only what the webhook's credential can read when it's sent. A delivery can arrive more than once: use delivery_id to recognize a repeat.

Header parameters

X-Marfa-Signature*string

t=<unix seconds>,v1=<hex>, where v1 is the HMAC-SHA256 of <t>.<raw body> under the webhook's secret. Check it, and that t is recent, before you trust the body.

X-Marfa-Event-Type*string

The event, the same as event_type in the body.

Value in"item.created""item.updated""item.trashed""item.restored""item.purged""item.state_changed""metadata.changed""rows.changed""edge.created""edge.updated""edge.deleted""attention.raised"

Request body

application/json
  1. body

The body of a webhook delivery of an item event.

event_type*string

The event, which is also the frame's event:.

Value in"item.created""item.updated""item.trashed""item.restored""item.purged""item.state_changed""metadata.changed"
item*

The item after the change. On item.trashed and item.purged of an item a cascade trashed, it carries trashed_by_cascade, and trashed_with if you can read that item's type.

metadata*|

The item's tags and extensions after the change, or before it on item.purged, with only the namespaces you can read. A webhook sends null.

restored_with?string

On item.restored of an item another item's restore brought back: the ID of that item, if you can read its type.

listed?boolean

Only on a copy stream: true if the item is in the set you can list, false if you can read it only by ID.

event_id*string

The event's ID in the log, the same as its id: on GET /events.

delivery_id*string

The ID of the delivery, the same on every attempt. Use it to recognize a repeat.

delivered_at*string

When Marfa sent this attempt, in UTC.

Response body

Marfa records the delivery as succeeded. It doesn't read the response body.

Any other answer is a failure. On a 3xx, or a 4xx other than 408 and 429, the delivery becomes failed. On a 408, 429 or 5xx, no answer within 10 seconds or no connection, Marfa tries again after at least 1, 5, 25, 125, 625, 3125 and 15625 seconds, and as long as Retry-After asks, up to 5 minutes. After 8 attempts, it's failed.

Example requests

The body of a webhook delivery: the event, with its ID and the delivery's.

POST/event