Subscribe to notifications

Allow users to subscribe to or manage their email notifications for OpenCover covers using the API.

Notifications inform users about important events related to their cover, such as upcoming expiry.

Overview

1. Check status & get consent message: query the API to check if the user is already subscribed and retrieve a consent message.

2. Generate signature: Prompt the user to sign the consent message with their wallet to prove ownership.

3. Subscribe / update / view: Use the generated signature to either:

   1. Subscribe a new email address for notifications or update an existing one.

   2. View the full registered email address (optional).

1️⃣ Check notification status & get consent message

Endpoint

GET https://opencover.com/api/user/:address/:chainId

API reference

Response

• If the user is subscribed, the response body includes an obfuscated email address (e.g., e***@e***.c**).

• Crucially, the response includes the X-OC-Sign header. This contains a Base64-encoded consent message that the user must sign in the next step.

• If the user is not found (404) or requires re-authentication (401), the X-OC-Sign header is still provided.

See the OpenCover API reference for full response details.

2️⃣ Generate signature

Before subscribing or viewing the full email address, the user must sign the consent message obtained from the X-OC-Sign header in the previous step. This verifies their control over the wallet.

1. Decode the Base64-encoded message from the X-OC-Sign header.

2. Use a library like wagmi to prompt the user to sign the decoded message string.

import { signMessage } from '@wagmi/core'
import axios from 'axios';
import { config } from './config'

const res = await axios.get(...); // API response from Step 1

const address = '0x55a4E29C0aFE0b8fE829757A2c80475ec6bEFea6'; // User's wallet address

const message = atob(res.headers.get('x-oc-sign')); // Decoded consent message

const signature = await signMessage(config, {
  account: address,
  message,
});

The resulting signature string is used in the subsequent API calls.

3️⃣ Subscribe or update email

To subscribe a new email address for notifications or update an existing one, make a POST request to the user endpoint. This request must include the signature from Step 2.

Endpoint

POST https://opencover.com/api/user
X-OC-Signature: <the signature string generated in Step 2>

API reference

Request & response

{
  "address": "0x55a4E29C0aFE0b8fE829757A2c80475ec6bEFea6", // User's wallet address
  "chainId": 8453,
  "email": "[email protected]"
}

A successful (201) response confirms the subscription/update and returns the user details, including the newly set email address.

4️⃣ View full email (optional)

To retrieve the user's full, non-obfuscated email address (if they are already subscribed), make the same GET request as in Step 1, but include the signature obtained in Step 2.

Endpoint

GET https://opencover.com/api/user/:address/:chainId
X-OC-Signature: <the signature string generated in Step 2>

API reference

Response

If the signature is valid, the email field in the response body will contain the full email address.