Create a webhook
Creates a webhook that sends the events you name to url. It belongs to your key, or your app's grant: Marfa deletes it when that is revoked, and sends nothing while it lacks webhooks.manage or the key has expired.
bearerAuthAuthorizationBearer <token>Authenticate with an API key (marfa_k1_…) or an OAuth access token (marfa_at_…).
X-Marfa-Instance-Id?stringThe ID of the instance you expect, as GET / returns it. If another instance answers at this address, Marfa returns 409 instance_changed and doesn't write. Leave it out to send the request to whichever instance answers.
^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$application/json- body
url*stringThe URL Marfa posts events to: http or https, with no user name or password. Unless the instance allows private addresses, it must reach a public address: Marfa refuses a URL whose host resolves to a private one, and checks again at each delivery.
1 <= lengthevents*array<>The events to send. Name each one: there's no wildcard.
1 <= itemstype_filter?|Send item events only for this type and its subtypes, such as core.media, or for every type a pattern such as app.* matches. The type needn't be registered. Edge events aren't filtered. Leave it out, blank or null for every type.
secret?stringThe key Marfa signs each delivery with. Leave it out for Marfa to generate one.
32 <= lengthReturns the new webhook with its whole secret, which no other response shows. Use it to check each delivery's X-Marfa-Signature.
application/json- response
A webhook sends the events you choose, as you can read them, to a URL.
id*stringUnique identifier for the webhook.
url*stringThe URL Marfa posts events to.
events*array<string>The events Marfa sends, such as item.created.
type_filter*|The type, with its subtypes, or the pattern whose item events Marfa sends. null when Marfa sends item events of every type. Edge events aren't filtered.
secret*stringThe key Marfa signs each delivery with. Only POST /webhooks returns it whole; other responses show **** and its last four characters.
active*booleantrue if Marfa sends events to the webhook.
created_at*stringWhen the webhook was created, in UTC.
updated_at*stringWhen the webhook last changed, in UTC.
validation_error: a field is invalid. For example,urlisn'thttporhttps, carries a user name or password, or names an IP address that isn't public;eventsis empty or names an unknown event or*;secretis too short; ortype_filteris*, malformed or a list; or the body has a field this endpoint doesn't take.missing_required_field:urloreventsis missing.
application/json- response
An error response.
error*What went wrong.
unauthorized: the request has no credential, or its credential is not valid. For a key that has expired, details.expired_at says when it expired.
application/json- response
An error response.
error*What went wrong.
forbidden: you don't havewebhooks.manage.
application/json- response
An error response.
error*What went wrong.
request_timeout: the request body didn't arrive whole within 180 seconds. Nothing changed, and Marfa closed the connection. Send the request again. A body larger than about 21 MiB can't arrive in that time over a 1 Mbit/s link, so send it in smaller requests.
application/json- response
An error response.
error*What went wrong.
conflict: You already hold 100 webhooks. Delete one, then register this one.details.reasoniswebhook_capanddetails.capis100.instance_changed:X-Marfa-Instance-Idnames another instance. Nothing is written. Rebuild the working copy from the instance at this address.
application/json- response
An error response.
error*What went wrong.
contract_mismatch: X-Marfa-Contract names another contract version than this instance speaks, or is not a whole number. Nothing was done.
application/json- response
An error response.
error*What went wrong.
request_too_large: the request body is larger than this instance accepts.
application/json- response
An error response.
error*What went wrong.
rate_limited: you sent too many requests. Wait for the number of seconds in Retry-After, then try again.
application/json- response
An error response.
error*What went wrong.
internal_error: Marfa failed in a way it didn't expect, and the request may not have completed. Read what you changed before you repeat a write.
application/json- response
An error response.
error*What went wrong.
write_contention: the database was busy, and Marfa couldn't complete the request in time. Nothing changed. Try the request again. While a restore runs, details.reason is restore_running.
application/json- response
An error response.
error*What went wrong.
insufficient_storage: the disk that holds the instance's data has no room for the request, or the request would leave less free than the instance keeps in reserve. Nothing changed, unless details.write_outcome is unknown, which means the write may have landed: read what you changed before you repeat it. Free space on the disk, then try the request again.
application/json- response
An error response.
error*What went wrong.
curl -X POST 'http://localhost:8600/webhooks' \ -H 'Content-Type: application/json' \ -d '{ "url": "string", "events": [ "item.created" ]}'{ "id": "01a1011f-f8a6-7d27-8213-d126f553409e", "url": "https://hooks.example.com/marfa", "events": [ "item.created", "item.updated" ], "type_filter": "acme.deal", "secret": "b65d38b03fdd936af205fe4d2468727c8be397a5decde1bdf1e07e43e4c4deb0", "active": true, "created_at": "2026-10-03T09:56:05.889Z", "updated_at": "2026-10-03T09:56:05.889Z"}