Browse the docs

Create webhook

POST /v1/api-gateway/webhook

Registers the webhook URL and returns the signing secret used to verify delivery signatures. The secret appears ONLY in this response and in the rotate response — store it now, there is no endpoint that reads it back. Re-registering replaces the previous webhook, issues a new secret and invalidates the previous one. The URL must be a publicly reachable http(s) endpoint; it is probed with a POST during registration and must not answer with a 5xx.

Request

Authentication: your API key in the x-api-key header.

Headers

Field	Type	Description
`Idempotency-Key`	string	A unique string you choose, up to 255 characters, that makes this request safe to retry. If a request times out or fails in transit, send it again with the same key: the status code and body of the first attempt are returned and the operation is not performed a second time. Stored replies — including failures — are replayed for 24 hours, after which the same key starts a fresh request. Reusing a key for a different request, or sending it while the first request is still running, returns 409. Omit the header and the request behaves exactly as before. Document upload endpoints do not accept it.

Body

Field	Type	Description
`url` required	string, uri	Absolute `http`/`https` URL that will receive webhook POSTs. Must resolve to a public host (no private/reserved IPs, no embedded credentials); it is probed with a POST on registration and must not answer with a network error or 5xx.

Example request

cURL

curl --request POST \
     --url 'https://api.themooncard.com/v1/api-gateway/webhook' \
     --header 'x-api-key: YOUR_API_KEY' \
     --header 'content-type: application/json' \
     --data '{
       "url": "https://example.com/moon/webhooks"
     }'

Responses

201 Success

Field	Type	Description
`message` required	string
`signing_secret` required	string	HMAC signing secret for verifying webhook payloads. Shown only on create/rotate. Always 49 characters: the `whsec_` prefix plus 43 base64url characters.

JSON

{
  "message": "Webhook created successfully",
  "signing_secret": "whsec_7Jd2Kq9Xr4Tn6Vb1Zc8Ye3Aw5Sh0Pl2Mg7Uf4Jx6Rk9"
}

400 Error

Validation failed (errors[]), or { message, code } with WEBHOOK_URL_NOT_ALLOWED (not a public http(s) endpoint) or ERROR_SENDING_POST_REQUEST (the probe failed or returned 5xx).

The body is the standard error object: see Errors.

401 Error

Missing or invalid credentials, e.g. { "message": "Invalid API Key", "code": "UNAUTHORIZED" }.

The body is the standard error object: see Errors.

409 Error

The Idempotency-Key you sent is already in use. IDEMPOTENCY_KEY_REUSED — the key was used for a different request; send a new key, or repeat the original request exactly to receive its stored response. IDEMPOTENCY_KEY_IN_PROGRESS — the first request with this key has not finished yet; retry in a few seconds.

The body is the standard error object: see Errors.

500 Error

Unexpected server error. Body is { message: "Internal server error", code: "INTERNAL_SERVER_ERROR" }.

The body is the standard error object: see Errors.

Last updated September 4, 2026