Medblocks Webhooks API
The Webhooks API from Medblocks — 4 operation(s) for webhooks.
The Webhooks API from Medblocks — 4 operation(s) for webhooks.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/medblocks-webhooks-api"
curl "https://apis.io/api/v1/apis?limit=25"
Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Medblocks Webhooks API
version: '2026-04-25'
description: 'Developer API for the Medblocks Platform.
Connect any patient to one or more EHRs (Epic, Cerner, Athena, …) via a single hosted PatientSession, then pull their unified FHIR records through this API. Server-to-server only — no browser-side calls. Authenticate every request with a Bearer secret key.
**Resources:** `PatientSession`, `Patient`, `Connection`, `FhirSource`. **Conventions:** date-pinned versioning (optional `Version` header), a typed error envelope on every non-2xx response.'
license:
name: Proprietary
url: https://medblocks.com/terms
servers:
- url: https://app.medblocks.com
security:
- BearerAuth: []
tags:
- name: Webhooks
paths:
/webhooks:
post:
operationId: api.createWebhook
summary: Register a webhook endpoint
description: Register an HTTPS endpoint to receive signed event deliveries. The signing `secret` is returned once in this response.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookEndpointCreateInput'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookEndpointWithSecret'
'400':
description: '400'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'401':
description: '401'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'403':
description: '403'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'404':
description: '404'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'409':
description: '409'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'429':
description: '429'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
headers:
Retry-After:
$ref: '#/components/headers/RetryAfter'
'500':
description: '500'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
parameters:
- $ref: '#/components/parameters/Version'
tags:
- Webhooks
get:
operationId: api.listWebhooks
summary: List webhook endpoints
description: List your organization's webhook endpoints with cursor pagination and an optional `status` filter. Secrets are never returned.
parameters:
- name: limit
in: query
schema:
type: integer
minimum: 1
maximum: 100
default: 10
description: Maximum number of items to return.
allowEmptyValue: true
allowReserved: true
- name: starting_after
in: query
schema:
type: string
description: Pagination cursor from `next_cursor`.
allowEmptyValue: true
allowReserved: true
- name: status
in: query
schema:
enum:
- active
- disabled
type: string
description: Filter by lifecycle status.
allowEmptyValue: true
allowReserved: true
- $ref: '#/components/parameters/Version'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
resource_type:
const: list
description: Resource type discriminator. Always `"list"` for paginated responses.
data:
type: array
items:
$ref: '#/components/schemas/WebhookEndpoint'
description: Items on this page.
has_more:
type: boolean
description: '`true` when there''s at least one more page after this one.'
next_cursor:
anyOf:
- type: string
- type: 'null'
description: Pass as `starting_after` to fetch the next page. `null` when there's no more data.
required:
- resource_type
- data
- has_more
- next_cursor
examples:
- resource_type: list
data:
- id: wh_01J9YR9N3X4VZ6P2K5RH7M3LMP
resource_type: webhook_endpoint
url: https://api.fhirapp.com/medblocks/webhook
events:
- patient_session.completed
- connection.token_refresh_failed
status: active
description: Production webhook
metadata: {}
api_version: '2026-04-25'
created_at: '2026-04-25T14:30:00.000Z'
updated_at: '2026-04-25T14:30:00.000Z'
has_more: false
next_cursor: null
'400':
description: '400'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'401':
description: '401'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'403':
description: '403'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'404':
description: '404'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'409':
description: '409'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'429':
description: '429'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
headers:
Retry-After:
$ref: '#/components/headers/RetryAfter'
'500':
description: '500'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
tags:
- Webhooks
/webhooks/{id}:
get:
operationId: api.getWebhook
summary: Retrieve a webhook endpoint
description: Retrieve a single webhook endpoint by its `wh_` id, including its URL, subscribed events, and status. The secret is never returned.
parameters:
- name: id
in: path
required: true
schema:
type: string
description: Webhook endpoint id (`wh_*`).
- $ref: '#/components/parameters/Version'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookEndpoint'
'400':
description: '400'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'401':
description: '401'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'403':
description: '403'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'404':
description: '404'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'409':
description: '409'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'429':
description: '429'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
headers:
Retry-After:
$ref: '#/components/headers/RetryAfter'
'500':
description: '500'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
tags:
- Webhooks
patch:
operationId: api.updateWebhook
summary: Update a webhook endpoint
description: Partially update a webhook endpoint's URL, subscribed events, description, or metadata, or re-enable it with `status` active.
parameters:
- name: id
in: path
required: true
schema:
type: string
description: Webhook endpoint id (`wh_*`).
- $ref: '#/components/parameters/Version'
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
url:
type: string
format: uri
events:
type: array
minItems: 1
maxItems: 5
items:
anyOf:
- const: '*'
- enum:
- patient_session.completed
- connection.token_refresh_failed
- records.sync.completed
- records.sync.failed
type: string
description: Event-type filter. Either `["*"]` (deliver all events) or an explicit list of event types. Unknown types are rejected.
description:
anyOf:
- type: string
maxLength: 500
- type: 'null'
metadata:
type: object
propertyNames:
type: string
additionalProperties: {}
status:
enum:
- active
- disabled
type: string
description: Lifecycle status. `active` accepts deliveries; `disabled` skips them. Auto-flipped to `disabled` after the delivery worker exhausts retries on this endpoint.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookEndpoint'
'400':
description: '400'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'401':
description: '401'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'403':
description: '403'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'404':
description: '404'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'409':
description: '409'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'429':
description: '429'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
headers:
Retry-After:
$ref: '#/components/headers/RetryAfter'
'500':
description: '500'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
tags:
- Webhooks
delete:
operationId: api.deleteWebhook
summary: Delete a webhook endpoint
description: Permanently delete a webhook endpoint and its delivery history. Returns a tombstone confirming the deletion.
parameters:
- name: id
in: path
required: true
schema:
type: string
description: Webhook endpoint id (`wh_*`).
- $ref: '#/components/parameters/Version'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookEndpointDeleted'
'400':
description: '400'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'401':
description: '401'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'403':
description: '403'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'404':
description: '404'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'409':
description: '409'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'429':
description: '429'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
headers:
Retry-After:
$ref: '#/components/headers/RetryAfter'
'500':
description: '500'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
tags:
- Webhooks
/webhooks/{id}/rotate-secret:
post:
operationId: api.rotateWebhookSecret
summary: Rotate the signing secret for a webhook endpoint
description: Generate a new signing secret for a webhook endpoint, invalidating the old one. The new secret is returned once in this response.
parameters:
- name: id
in: path
required: true
schema:
type: string
description: Webhook endpoint id (`wh_*`).
- $ref: '#/components/parameters/Version'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookEndpointWithSecret'
'400':
description: '400'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'401':
description: '401'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'403':
description: '403'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'404':
description: '404'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'409':
description: '409'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'429':
description: '429'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
headers:
Retry-After:
$ref: '#/components/headers/RetryAfter'
'500':
description: '500'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
tags:
- Webhooks
/webhooks/{id}/events:
get:
operationId: api.listWebhookEvents
summary: List recent webhook events for an endpoint
description: List recent delivery records for one endpoint with cursor pagination and an optional `delivered` filter for the delivery audit.
parameters:
- name: id
in: path
required: true
schema:
type: string
description: Webhook endpoint id (`wh_*`).
- name: limit
in: query
schema:
type: integer
minimum: 1
maximum: 100
default: 10
description: Maximum number of items to return.
allowEmptyValue: true
allowReserved: true
- name: starting_after
in: query
schema:
type: string
description: Pagination cursor from `next_cursor`.
allowEmptyValue: true
allowReserved: true
- name: delivered
in: query
schema:
enum:
- 'true'
- 'false'
type: string
description: Filter by delivery state. `true` = only delivered events; `false` = only pending/failed.
allowEmptyValue: true
allowReserved: true
- $ref: '#/components/parameters/Version'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
resource_type:
const: list
description: Resource type discriminator. Always `"list"` for paginated responses.
data:
type: array
items:
$ref: '#/components/schemas/WebhookEvent'
description: Items on this page.
has_more:
type: boolean
description: '`true` when there''s at least one more page after this one.'
next_cursor:
anyOf:
- type: string
- type: 'null'
description: Pass as `starting_after` to fetch the next page. `null` when there's no more data.
required:
- resource_type
- data
- has_more
- next_cursor
examples:
- resource_type: list
data:
- id: evt_01J9YR9N3X4VZ6P2K5RH7M3LMP
resource_type: event
webhook_endpoint_id: wh_01J9YR9N3X4VZ6P2K5RH7M3LMP
type: patient_session.completed
data:
object:
id: ps_01J9YQ8M2X4VZ6P2K5RH7M3KQT
resource_type: patient_session
status: complete
patient_id: user_42
api_version: '2026-04-25'
attempts: 1
next_attempt_at: null
delivered_at: '2026-04-25T14:35:02.000Z'
last_status_code: 200
last_response_body: ok
last_redelivered_at: null
created_at: '2026-04-25T14:35:00.000Z'
has_more: false
next_cursor: null
'400':
description: '400'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'401':
description: '401'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'403':
description: '403'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'404':
description: '404'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'409':
description: '409'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'429':
description: '429'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
headers:
Retry-After:
$ref: '#/components/headers/RetryAfter'
'500':
description: '500'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
tags:
- Webhooks
components:
parameters:
Version:
name: Version
in: header
required: false
description: Date-pinned API version. If omitted, Medblocks uses the version pinned on your API key.
example: '2026-04-25'
schema:
type: string
schemas:
WebhookEvent:
type: object
properties:
id:
type: string
description: Public id, prefixed `evt_`.
resource_type:
const: event
webhook_endpoint_id:
type: string
description: The `wh_*` endpoint this delivery targets.
type:
enum:
- patient_session.completed
- connection.token_refresh_failed
- records.sync.completed
- records.sync.failed
type: string
description: Event type discriminator.
data:
type: object
properties:
object:
description: Event-specific payload. Shape depends on `type` — see the SDK's typed `WebhookEvent` union for the discriminated shape.
api_version:
type: string
description: API version pinned at the endpoint at fire time.
attempts:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
description: Number of delivery attempts made so far (incl. the current one).
next_attempt_at:
anyOf:
- type: string
- type: 'null'
description: ISO 8601 timestamp of the next scheduled retry. Null when terminal (delivered or exhausted).
delivered_at:
anyOf:
- type: string
- type: 'null'
description: ISO 8601 timestamp of successful delivery. Null until a 2xx response is received.
last_status_code:
anyOf:
- type: integer
minimum: -9007199254740991
maximum: 9007199254740991
- type: 'null'
description: HTTP status code from the most recent attempt.
last_response_body:
anyOf:
- type: string
- type: 'null'
description: Response body from the most recent attempt, truncated to 4 KB.
last_redelivered_at:
anyOf:
- type: string
- type: 'null'
description: ISO 8601 timestamp of the most recent manual redelivery. Null if never redelivered.
created_at:
type: string
required:
- id
- resource_type
- webhook_endpoint_id
- type
- data
- api_version
- attempts
- next_attempt_at
- delivered_at
- last_status_code
- last_response_body
- last_redelivered_at
- created_at
examples:
- id: evt_01J9YR9N3X4VZ6P2K5RH7M3LMP
resource_type: event
webhook_endpoint_id: wh_01J9YR9N3X4VZ6P2K5RH7M3LMP
type: patient_session.completed
data:
object:
id: ps_01J9YQ8M2X4VZ6P2K5RH7M3KQT
resource_type: patient_session
status: complete
patient_id: user_42
api_version: '2026-04-25'
attempts: 1
next_attempt_at: null
delivered_at: '2026-04-25T14:35:02.000Z'
last_status_code: 200
last_response_body: ok
last_redelivered_at: null
created_at: '2026-04-25T14:35:00.000Z'
ErrorEnvelope:
type: object
properties:
error:
type: object
properties:
type:
type: string
description: Error category (e.g. authentication_error, permission_error, conflict_error).
code:
type: string
description: Stable code within the type (e.g. invalid_api_key, external_id_already_exists).
message:
type: string
description: Human-readable error message.
param:
anyOf:
- type: string
- type: 'null'
description: Affected request parameter, if applicable.
doc_url:
type: string
description: Link to the API errors reference.
request_id:
type: string
description: Correlation id - include in support tickets. Echoes the `X-Request-Id` response header.
required:
- type
- code
- message
- param
- doc_url
- request_id
required:
- error
examples:
- error:
type: authentication_error
code: invalid_api_key
message: API key invalid
param: null
doc_url: https://medblocks.com/docs/reference/errors
request_id: 9c9b6f7a-8e4f-4a3b-9c1e-6f3a2d8b7c4d
WebhookEndpointDeleted:
type: object
properties:
id:
type: string
resource_type:
const: webhook_endpoint
deleted:
const: true
required:
- id
- resource_type
- deleted
examples:
- id: wh_01J9YR9N3X4VZ6P2K5RH7M3LMP
resource_type: webhook_endpoint
deleted: true
WebhookEndpointCreateInput:
type: object
properties:
url:
type: string
format: uri
description: Your HTTPS endpoint that receives event deliveries. `http://localhost` is allowed for local dev only.
events:
type: array
minItems: 1
maxItems: 5
items:
anyOf:
- const: '*'
- enum:
- patient_session.completed
- connection.token_refresh_failed
- records.sync.completed
- records.sync.failed
type: string
description: Event-type filter. Either `["*"]` (deliver all events) or an explicit list of event types. Unknown types are rejected.
description:
type: string
maxLength: 500
description: Human-readable label, visible in the dashboard.
metadata:
type: object
propertyNames:
type: string
additionalProperties: {}
description: Up to 50 keys of arbitrary developer metadata. Echoed back on every read.
required:
- url
- events
examples:
- url: https://api.fhirapp.com/medblocks/webhook
events:
- patient_session.completed
- records.sync.completed
description: Production webhook
metadata: {}
WebhookEndpoint:
type: object
properties:
id:
type: string
description: Public id, prefixed `wh_`.
resource_type:
const: webhook_endpoint
description: Resource type discriminator. Always `"webhook_endpoint"`.
url:
type: string
description: Your HTTPS endpoint URL.
events:
type: array
items:
type: string
description: Event-type filter. `["*"]` means all events; otherwise the list of subscribed event types.
status:
enum:
- active
- disabled
type: string
description: Lifecycle status. `active` accepts deliveries; `disabled` skips them. Auto-flipped to `disabled` after the delivery worker exhausts retries on this endpoint.
description:
anyOf:
- type: string
- type: 'null'
description: Human-readable label. Null if never set.
metadata:
type: object
propertyNames:
type: string
additionalProperties: {}
description: Developer-supplied metadata key/value pairs.
api_version:
type: string
description: API version pinned at registration time. Immutable. Copied onto every `webhook_event.api_version` this endpoint fires.
created_at:
type: string
updated_at:
type: string
required:
- id
- resource_type
- url
- events
- status
- description
- metadata
- api_version
- created_at
- updated_at
examples:
- id: wh_01J9YR9N3X4VZ6P2K5RH7M3LMP
resource_type: webhook_endpoint
url: https://api.fhirapp.com/medblocks/webhook
events:
- patient_session.completed
- connection.token_refresh_failed
status: active
description: Production webhook
metadata: {}
api_version: '2026-04-25'
created_at: '2026-04-25T14:30:00.000Z'
updated_at: '2026-04-25T14:30:00.000Z'
WebhookEndpointWithSecret:
type: object
properties:
id:
type: string
description: Public id, prefixed `wh_`.
resource_type:
const: webhook_endpoint
description: Resource type discriminator. Always `"webhook_endpoint"`.
url:
type: string
description: Your HTTPS endpoint URL.
events:
type: array
items:
type: string
description: Event-type filter. `["*"]` means all events; otherwise the list of subscribed event types.
status:
enum:
- active
- disabled
type: string
description: Lifecycle status. `active` accepts deliveries; `disabled` skips them. Auto-flipped to `disabled` after the delivery worker exhausts retries on this endpoint.
description:
anyOf:
- type: string
- type: 'null'
description: Human-readable label. Null if never set.
metadata:
type: object
propertyNames:
type: string
additionalProperties: {}
description: Developer-supplied metadata key/value pairs.
api_version:
type: string
description: API version pinned at registration time. Immutable. Copied onto every `webhook_event.api_version` this endpoint fires.
created_at:
type: string
updated_at:
type: string
secret:
type: string
description: The signing secret (`whsec_*`). Returned ONCE on create and rotate-secret. Store it server-side; you cannot retrieve it later.
required:
- id
- resource_type
- url
- events
- status
- description
- metadata
- api_version
- created_at
- updated_at
- secret
examples:
- id: wh_01J9YR9N3X4VZ6P2K5RH7M3LMP
resource_type: webhook_endpoint
url: https://api.fhirapp.com/medblocks/webhook
events:
- patient_session.completed
- connection.token_refresh_failed
status: active
description: Production webhook
metadata: {}
api_version: '2026-04-25'
created_at: '2026-04-25T14:30:00.000Z'
updated_at: '2026-04-25T14:30:00.000Z'
secret: whsec_01J9YR9N3X4VZ6P2K5RH7M3LMPabcdef0123456789abcdef0123456789
headers:
RetryAfter:
description: Whole seconds to wait before retrying a rate-limited request.
schema:
type: integer
minimum: 1
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: API key (mb_sk_live_...)
description: Medblocks API key for server-side requests.