Managing Endpoints

mb.webhooks is the resource on @medblocks/connect for managing endpoints. Registering new ones, listing what you have, rotating secrets, and inspecting recent deliveries. For receiving and verifying incoming events, see Quickstart and Signatures.

Create

create returns the endpoint with the plaintext signing secret. The secret is returned exactly once. Store it server-side immediately.

import { mb } from "../medblocks";

const endpoint = await mb.webhooks.create({
  url: "https://api.example.com/medblocks/webhook",
  events: ["patient_flow.completed", "records.sync.completed"],
  description: "Production webhook",
});

console.log(endpoint.id);     // wh_*
console.log(endpoint.secret); // whsec_* - store me!

Subscribing To All Events

Pass ["*"] to deliver every event type. Otherwise list the explicit event types you want; any unknown type is rejected.

await mb.webhooks.create({
  url: "https://api.example.com/medblocks/webhook",
  events: ["*"],
});

Retrieve

const endpoint = await mb.webhooks.retrieve("wh_01J9YR9N3X4VZ6P2K5RH7M3LMP");

Returns the endpoint without the secret.

List

Cursor-paginated. Filter by status (active or disabled).

const page = await mb.webhooks.list({ limit: 50 });
for (const ep of page.data) console.log(ep.id, ep.url, ep.status);

for await (const ep of mb.webhooks.list({ status: "active" }).autoPagingIterator()) {
  console.log(ep.id);
}

Update

Partial update via PATCH. Only the fields you pass are changed. Use status: "active" to re-enable an endpoint that was auto-disabled after retry exhaustion.

const updated = await mb.webhooks.update("wh_01J9YR9N3X4VZ6P2K5RH7M3LMP", {
  status: "active",
});

Updatable fields: url, events, description, metadata, status. The endpoint’s api_version is immutable.

Delete

Drops any pending deliveries for this endpoint. Returns a tombstone.

const tombstone = await mb.webhooks.delete("wh_01J9YR9N3X4VZ6P2K5RH7M3LMP");
// { id: "wh_*", resource_type: "webhook_endpoint", deleted: true }

Rotate Secret

Generates a new signing secret and returns it. The old secret stops verifying immediately. There is no grace period.

const rotated = await mb.webhooks.rotateSecret("wh_01J9YR9N3X4VZ6P2K5RH7M3LMP");
await secrets.put("MEDBLOCKS_WEBHOOK_SECRET", rotated.secret);

List Recent Deliveries

listEvents returns the per-endpoint delivery log. Useful for a dashboard view or for debugging a flaky receiver.

const page = await mb.webhooks.listEvents("wh_01J9YR9N3X4VZ6P2K5RH7M3LMP", { limit: 20 });
for (const evt of page.data) {
  console.log(evt.id, evt.type, evt.last_status_code, evt.attempts);
}

Each WebhookEventRecord carries attempts, next_attempt_at, delivered_at, last_status_code, last_response_body (truncated to 4 KB), and last_redelivered_at. Use these to spot endpoints climbing toward auto-disable.

Errors

See SDK · Errors.

Related

• Concept · Webhooks. Model and lifecycle.
• Quickstart. Register, receive, verify, respond.
• Signatures. Medblocks.webhooks.constructEvent and the raw-body trap.
• Redelivery. Manual re-enqueue via mb.events.redeliver.
• Reference · Register a webhook endpoint. Exact schema.