Push

Set up the push provider

  • Sandbox: available
  • On your own host? Choose https://{host} in the playground.
POST
/v1/push/provider

Sets up the provider your current project sends push through. The credentials are checked with the provider first, then stored encrypted with a key of the project's own, and never returned.

Scope: the caller's project (from the token).

Behaviour

  • provider picks the body:
    • fcm: secret is the Firebase service account key, the JSON file as text. Sends to Android, iOS and web tokens.
    • apns: secret is the .p8 auth key (PEM), with teamId, keyId, bundleId (the APNs topic) and environment (production or sandbox). Sends to iOS tokens.
    • expo: secret is an Expo access token, or null (the default) when the Expo project does not require one. Sends to Expo push tokens.
    • relay: url, an https URL on a public host. Use it for any other provider (OneSignal, SNS, an in-house gateway): ovok POSTs one push.send per person, signed with Standard Webhooks, and your endpoint sends it on.
  • The check before storing: FCM exchanges the key for an access token with Google, APNs signs a token with the key, and the relay's host must resolve to public addresses only. A refusal is 422 INVALID_CREDENTIALS. A provider that cannot be reached is 502 PUSH_PROVIDER_UNAVAILABLE, and nothing is stored.
  • For a relay, the answer carries secret, the whsec_ key the deliveries are signed with. It is shown this once. To get a new one, remove the relay and set it up again.
  • A project sends through one provider. One already set up is 409 PROVIDER_CONFIGURED: change it with PATCH /v1/push/provider, or remove it with DELETE first.
  • When the server has no encryption key, nothing is stored and the answer is 503 ENCRYPTION_UNAVAILABLE.
  • A 409 without a code means the project changed while the server wrote. Read it again and retry.
  • The answer is 201, with the provider as GET /v1/push/provider returns it.

The relay call

POST <url>webhook-id: msg_…webhook-timestamp: <unix seconds>webhook-signature: v1,<base64 HMAC-SHA256>Content-Type: application/json{ "type": "push.send",  "data": { "recipient": { "reference": "Practitioner/…" },            "devices": [{ "id": "…", "token": "…", "platform": "ios" }],            "notification": { "title": "…", "body": "…" },            "data": { … } } }

Answer 2xx when sent, 410 when the person's devices are no longer registered (they are removed), or 429 or 5xx to be retried.

Example

curl -X POST 'https://api.sandbox.ovok.com/v1/push/provider' \  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \  -H 'Content-Type: application/json' \  -d '{ "provider": "relay", "url": "https://push.example.com/ovok" }'

Who can call it: a project admin. See roles.

Authorization

bearer
headerAuthorizationBearer <JWT>

Request Body

application/json
  1. body
provider*"fcm"
Value in"fcm"
secret*string

The Firebase service account key: the JSON file, as text. Never returned.

Length1 <= length <= 10000

Response Body

The provider as set up; for a relay, with its signing secret, shown this once.

application/json
  1. response
projectId*string
provider*string

The provider push is sent through; null when none.

Value in"fcm""apns""expo""relay"
settings*

What the provider is set up with, never a secret; null when none.

secret*string

The relay's whsec_ signing secret, answered once when the relay is set up; null otherwise.

Example Request
curl -X POST 'https://api.sandbox.ovok.com/v1/push/provider' \  -H 'Content-Type: application/json' \  -d '{  "provider": "fcm",  "secret": "string"}'
Example Response
{  "projectId": "string",  "provider": "fcm",  "settings": {    "property1": "string",    "property2": "string"  },  "secret": "string"}

Get the project's push provider GET

Returns the provider your current project sends push through, and what it is set up with. It never returns a secret. **Scope:** the caller's project (from the token). ## Behaviour - `provider` is `fcm`, `apns`, `expo` or `relay`, or `null` when none is set up. - `settings` shows the setup without its secret, or `null`: - `fcm`: `firebaseProjectId` and `clientEmail` from the service account key. - `apns`: `teamId`, `keyId`, `bundleId` and `environment`. - `expo`: `accessToken`, whether one is stored. - `relay`: `url`. - `secret` is always `null` here. A relay's signing secret is shown once, when it is set up. - A config stored with another server's key reads as not set up; set it up again with `POST`. ## Example ```bash curl -X GET 'https://api.sandbox.ovok.com/v1/push/provider' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' ``` **Who can call it:** a project admin. See [roles](/access-policies#who-can-call-a-route).

Change the push provider PATCH

Changes the credentials or settings of the push provider your current project has set up. The result is checked with the provider before it is stored, as `POST` does. **Scope:** the caller's project (from the token). ## Behaviour - `provider` names the provider set up. Another one is 409 `PUSH_PROVIDER_MISMATCH`: remove the current one with `DELETE`, then set the new one up with `POST`. - Send the fields to change, with the rules of `POST`: - `fcm`: `secret`. - `apns`: any of `secret`, `teamId`, `keyId`, `bundleId` and `environment`. - `expo`: `secret`, or `null` to stop sending an access token. - `relay`: `url`. The signing secret stays as it is. - No provider set up is 404 `PROVIDER_NOT_CONFIGURED`. - A refusal from the check is 422 `INVALID_CREDENTIALS`, an unreachable provider 502 `PUSH_PROVIDER_UNAVAILABLE`; nothing is stored either way. - When the server has no encryption key, nothing is stored and the answer is 503 `ENCRYPTION_UNAVAILABLE`. - The answer has the provider as `GET /v1/push/provider` returns it. ## Example ```bash curl -X PATCH 'https://api.sandbox.ovok.com/v1/push/provider' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \ -H 'Content-Type: application/json' \ -d '{ "provider": "apns", "environment": "production" }' ``` **Who can call it:** a project admin. See [roles](/access-policies#who-can-call-a-route).