Webhook endpoint objects, subscriptions, deliveries, replay, and secret rotation.
Webhook endpoints receive event POSTs. This resource manages the endpoints themselves - for payload format and signature verification see the Webhooks guide.
Meridian{
"id": "wh_2nQ8kLm4xP",
"object": "webhook_endpoint",
"project_id": "prj_9kLm2xVb7nQe",
"url": "https://api.acme.io/webhooks/meridian",
"events": ["project.updated", "sync.completed"],
"status": "active",
"created_at": "2026-08-14T09:31:07Z",
"disabled_at": null
}| Field | Notes |
|---|---|
url | HTTPS required in live; test allows HTTP tunnels |
events | Subscribed event types, or ["*"] for all |
status | active, paused (auto-disabled by failures), or disabled |
secret | whsec_… signing secret - returned once at creation |
/webhookscurl -X POST https://api.meridian.dev/v2/webhooks \
-H "Authorization: Bearer $MERIDIAN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"project_id": "prj_9kLm2xVb7nQe",
"url": "https://api.acme.io/webhooks/meridian",
"events": ["project.updated", "sync.completed"]
}'application/json/webhooksAccepts project_id, status, plus standard pagination (limit, cursor).
curl "https://api.meridian.dev/v2/webhooks?project_id=prj_9kLm2xVb7nQe" \
-H "Authorization: Bearer $MERIDIAN_API_KEY"/webhooks/:id/deliveries{
"id": "dlv_9fH3kQm7xT",
"object": "delivery",
"event_id": "evt_3kR8mPx2vL",
"status": "failed",
"response_status": 500,
"duration_ms": 1204,
"attempts": 2,
"next_attempt_at": "2026-09-17T11:11:22Z",
"delivered_at": null
}/webhooks/:id/deliveries/:delivery_id/replayRe-sends the event payload as a new delivery (fresh signature timestamp). Available for 30 days after the original delivery.
curl -X POST https://api.meridian.dev/v2/webhooks/wh_2nQ8kLm4xP/deliveries/dlv_9fH3kQm7xT/replay \
-H "Authorization: Bearer $MERIDIAN_API_KEY"/webhooks/:id/rotate_secretImmediately invalidates the old whsec_ and returns a new one. Deploy the new secret to your handler before the next delivery lands - rotations take effect instantly.
curl -X POST https://api.meridian.dev/v2/webhooks/wh_2nQ8kLm4xP/rotate_secret \
-H "Authorization: Bearer $MERIDIAN_API_KEY"| Status | Code | Condition |
|---|---|---|
400 | parameter_invalid | Non-HTTPS URL in live, or unknown event type |
403 | insufficient_scope | Key lacks webhooks:write |
404 | resource_not_found | No such endpoint/delivery in this environment |
410 | delivery_expired | Replay requested after the 30-day window |