OVOK DOCS
Get startedOvokSignalsSDKsGuidesAPI referenceDeveloper resources
Signals API - Events

List webhook events

  • Sandbox: available
  • Staging: available
  • Production: unknown
GET
/v1/signals/api/events

Every event addressed to the caller, oldest first and keyset paged by cursor, each with its delivery status and payload: expired, failed and held ones too. An event is listed once it is two minutes old, so a page never moves past one a slower transaction has yet to commit. Filter by types, status, patientId, or (for a MANAGER) subscriberId.

Through ovok

  • Who can call it: Manager apps, and users whose access policy grants the capabilities.
  • Capabilities, all required: signals_events:read. Project admins have every capability; client applications get no admin bypass.
  • If your access covers only some patients (anyone but project admins, manager or submitter apps, and anyone whose Patient access has no criteria), name them with patientId, each one you can read, at most 100. Signals then pages over just those patients, so pages and totals stay true. A patient is named by its Signals id, or by its Medplum Patient id where Signals takes a refId; ovok asks Signals which patient a Signals id is.

Authorization

headerAuthorizationBearer <JWT>

Query Parameters

cursor?string

Opaque keyset cursor: a previous answer's nextCursor, passed back verbatim.

Lengthlength <= 512
limit?number

Page size, 1 to 200. Defaults to 50.

Range1 <= value
types?array<string>

Only these event types, comma-separated: alert.trigger,patient.inactive.

Lengthlength <= 100
status?string

Only deliveries in this state.

Value in"failed""delivered""pending""expired""held"
patientId?string

Only events about this patient: its Signals id, as the payload's patient.

Lengthlength <= 128
subscriberId?string

Only this subscriber's deliveries, by Signals id or clientId. A subscriber may name only itself.

Lengthlength <= 128

Response Body

One page of events.

application/json
  1. response
items*array<>
nextCursor*string

Opaque keyset cursor. Pass it back as cursor for the next page; null means this page was the last. Do not construct or parse it.

Example Request
curl -X GET 'https://api.sandbox.ovok.com/v1/signals/api/events'
Example Response
{  "items": [    {      "id": "string",      "eventId": "string",      "eventType": "string",      "subscriberId": "string",      "status": "pending",      "attempts": 0,      "nextAttemptAt": "2019-08-24T14:15:22Z",      "lastStatusCode": 0,      "lastError": "string",      "createdAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z",      "redeliveredAt": "2019-08-24T14:15:22Z",      "payload": {}    }  ],  "nextCursor": "string"}

Rotate the webhook signing secret POST

Mints a new Standard Webhooks signing secret (`whsec_` and 32 random bytes) and returns it this once. Every delivery carries `webhook-id` and `webhook-timestamp`; once the subscriber has a secret it also carries `webhook-signature`, so a receiver verifies with the Standard Webhooks library. The secret it replaces keeps signing until `previousSecretExpiresAt` (24 h), so `webhook-signature` holds both and the receiver switches with no gap. Each rotation keeps only the secret it replaces, so rotate again only once the receiver uses the new one. The first call mints the subscriber's first secret. A MANAGER rotates any subscriber of its tenant; a SUBSCRIBER only its own. ### Through ovok - **Who can call it:** Manager apps, and users whose access policy grants the capabilities. - **Capabilities, all required:** `signals_webhooks:update`. Project admins have every capability; client applications get no admin bypass. - It can reach any patient of your project without naming one, so it is for callers that reach every patient: project admins, manager or submitter apps, and anyone whose Patient access has no criteria.

List a delivery's attempts GET

Each POST made for it, oldest first: when, how long, the status code or the error, and the first 2 KB of the answer. ### Through ovok - **Who can call it:** Manager apps, and users whose access policy grants the capabilities. - **Capabilities, all required:** `signals_events:read`. Project admins have every capability; client applications get no admin bypass. - It can reach any patient of your project without naming one, so it is for callers that reach every patient: project admins, manager or submitter apps, and anyone whose Patient access has no criteria.