Register an endpoint
Registers a URL of your system to receive events.
Registers a URL that receives the account events. The response carries the secret only once: keep it, you use it to verify the signature.
events: event types, with no repeats, or["*"]for all of them.- In production the URL must be
httpsand public. An internal address (localhost, private IP,*.internal) gives400withdetails.field = "url". Outside production,httpworks too.
The endpoint receives only the events that happen after it is created.
api_keyAuthorizationBearer <token>API key (mk_...)
Idempotency-Key?stringOptional. A unique value (for example a UUID), 1 to 255 characters, that makes the request safe to retry: repeating it with the same body within 24h returns the original response with Idempotency-Replayed: true instead of running the operation again. Scoped to your account. Reusing it with a different body returns 409.
1 <= length <= 255application/json- body
url*stringRequired. An https URL of your system, up to 2048 characters. Outside production http is accepted too; in production, internal addresses (localhost, private IPs) are refused.
urilength <= 2048description?|Optional. A note for you, 1 to 200 characters after trimming. Accepts null.
1 <= length <= 200events*array<|>Required. Event types to receive, at least one, or ["*"] for all of them.
1 <= items <= 36The endpoint was created. The body carries secret, which shows up only here: keep it to verify signatures.
application/json- response
The endpoint, with its signing secret.
id*stringOpaque unique identifier of the endpoint, generated by the API. Use it in the /v1/webhooks/endpoints/{id} routes and to filter deliveries.
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$uuidurl*stringWhere we send the events, with a POST.
description*|Your note about the endpoint. null when there is none.
events*array<|>Event types the endpoint receives, or ["*"] for every type, including future ones.
enabled*booleanfalse pauses the endpoint: new events skip it, and its pending deliveries fail without a call.
createdAt*stringWhen the endpoint was created, in ISO-8601 (UTC).
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$date-timeupdatedAt*stringWhen the endpoint last changed, in ISO-8601 (UTC).
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$date-timesecret*stringSecret to verify the signature of every delivery (X-Marketapi-Signature). It shows up only in this response (creation or rotation): keep it.
curl -X POST "https://example.com/v1/webhooks/endpoints" \ -H "Content-Type: application/json" \ -d '{ "url": "https://your-app.com/webhooks/marketapi", "events": [ "*" ] }'{ "id": "c2d3e4f5-a6b7-4c8d-9e0f-1a2b3c4d5e6f", "url": "https://your-app.com/webhooks/marketapi", "description": "Production", "events": [ "*" ], "enabled": true, "createdAt": "2026-10-06T14:20:00.000Z", "updatedAt": "2026-10-06T14:20:00.000Z", "secret": "whsec_4fJ9kL2mN7pQ1rS8tU3vW6xY0zA5bC4dE9fG2hJ7kLm"}