Set up the push provider
- Sandbox: available
- On your own host? Choose https://{host} in the playground.
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
providerpicks the body:fcm:secretis the Firebase service account key, the JSON file as text. Sends to Android, iOS and web tokens.apns:secretis the.p8auth key (PEM), withteamId,keyId,bundleId(the APNs topic) andenvironment(productionorsandbox). Sends to iOS tokens.expo:secretis an Expo access token, ornull(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 onepush.sendper 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 502PUSH_PROVIDER_UNAVAILABLE, and nothing is stored. - For a relay, the answer carries
secret, thewhsec_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 withPATCH /v1/push/provider, or remove it withDELETEfirst. - 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/providerreturns 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.
bearerAuthorizationBearer <JWT>application/json- body
provider*"fcm""fcm"secret*stringThe Firebase service account key: the JSON file, as text. Never returned.
1 <= length <= 10000The provider as set up; for a relay, with its signing secret, shown this once.
application/json- response
projectId*stringprovider*stringThe provider push is sent through; null when none.
"fcm""apns""expo""relay"settings*What the provider is set up with, never a secret; null when none.
secret*stringThe relay's whsec_ signing secret, answered once when the relay is set up; null otherwise.
curl -X POST 'https://api.sandbox.ovok.com/v1/push/provider' \ -H 'Content-Type: application/json' \ -d '{ "provider": "fcm", "secret": "string"}'{ "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).