API ReferenceWebhooksRegister a webhook endpoint

Register a webhook endpoint

POST/api/v1/webhooks idempotent

Returns the plaintext signing secret EXACTLY ONCE in the response.secret field. Capture it; no recovery path — rotation = delete + recreate. Requires Idempotency-Key header.

Parameters

description

stringbody

events*

array<string>body

url*

stringbody

Responses

Success body

{
  "status": 201,
  "message": "OK",
  "data": {
    "secret": "whsec_y7f0MNv_u0ARXlAJSOxTiaRfjyv9eWJQBlbdrlzRED8",
    "active": true,
    "consecutive_failures": 0,
    "created_at": "2026-05-28T07:44:23.908Z",
    "description": "Sample item",
    "disabled_at": null,
    "events": [
      "shipment.delivered"
    ],
    "id": "IM-2026-0528-9ZNCP3-1",
    "last_delivery_at": null,
    "livemode": false,
    "secret_last4": "RED8",
    "url": "https://example.com/hooks/merdi"
  }
}

Returned object

Field	Type	Sample
status	number	201
message	string	OK
data	object	{12 keys}

curl https://merdiexpress.com/api/api/v1/webhooks \ -X POST \ -H "Authorization: Bearer mk_test_rh9ABekJfP31cN7sQ8jKvLwY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com/hooks/merdi", "events": [ "shipment.delivered" ], "description": "" }'

{ "status": 201, "message": "OK", "data": { "secret": "whsec_y7f0MNv_u0ARXlAJSOxTiaRfjyv9eWJQBlbdrlzRED8", "active": true, "consecutive_failures": 0, "created_at": "2026-05-28T07:44:23.908Z", "description": "Sample item", "disabled_at": null, "events": [ "shipment.delivered" ], "id": "IM-2026-0528-9ZNCP3-1", "last_delivery_at": null, "livemode": false, "secret_last4": "RED8", "url": "https://example.com/hooks/merdi" } }