---
title: PushNotification
publisher: frostyfrog
license: MIT
piuri: https://didcomm.org/push-notification/2.0
status: Draft
summary: The Push Notification protocol allows recipients to choose how push notifications are sent to them.
tags: []
authors:
- name: Colton Wolkins
email: [e-mail]

---

## Roles

There are two roles in this protocol:
- `mediator`: The agent that will be notifying *recipients* of pending messages via push notifications.
- `recipient`: The agent requesting push notifications be sent when no other viable means of communication are available.

## Connectivity

This protocol consists of two different message requests from the `recipient` that should be replied to by the `mediator`:

- Status Request -> Status
- Webhook -> Status

## States

There are not really states in this protocol, as sending a message leaves both parties in the same state they were before.

## Basic Walkthrough

Using this protocol, either party can send a message to the other at any time. There are no rules about taking turns or requiring a response.

Messages are assumed to be made visible to the recipient or evaluated by automated processes.

## Design By Contract

No protocol specific errors exist. Any errors related to headers or other core features are documented in the appropriate places.

## Security

This protocol expects messages to be encrypted during transmission, and repudiable.

## Composition

Supported Goal Code | Notes
--- | ---

## Message Reference

**message**

Message Type URI: `https://didcomm.org/push-notification/2.0/set-webhook`

The `message` message is sent by the `sender` to the `recipient`. Note that the role is only specific to the creation of messages, and that both parties may play both roles.

Attributes:

`content` - content of the user intended message.

Supported decorators/headers:

- The message should indicate the language used in the message. DIDComm V1 and DIDComm V2 have different methods for this. See examples below.
- The time the message is sent must be included. DIDComm V2 uses the `created_time` header. DIDComm V1 must include a `sent_time` as a message attribute containing the timestamp in ISO 8601 UTC format.

**configure**
Sent by the `recipient` to the `mediator` to request a `status` message.

Message Type URI: `https://didcomm.org/push-notification/1.0/configure`

{
    "id": "123456780",
    "type": "https://didcomm.org/push-notification-webhook/1.0/configure",
    "body": {
        "type": "webhook",
        "uri": "https://example.com/api/{unique-id}/webhook"
    }
}

**request-status**
Sent by the `recipient` to the `mediator` to request a `status` message.

Message Type URI: `https://didcomm.org/push-notification/1.0/request-status`

{
    "id": "123456780",
    "type": "https://didcomm.org/push-notification-webhook/1.0/request-status",
    "body": {}
}

**status**
Sent by the `mediator` to the `recipient` to request a `status` message.

Message Type URI: `https://didcomm.org/push-notification/1.0/status`

{
    "id": "123456780",
    "type": "https://didcomm.org/push-notification-webhook/1.0/status",
    "body": {
        "type": "webhook",
        "uri": "https://example.com/api/{unique-id}/webhook",
        "active": true
    }
}

## Webhook Message Reference

POST https://example.com/api/{unique-id}/webhook HTTP/1.1
Connection: close
Host: example.com
User-Agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36
content-length: 127
webhook-id: 53bf81b8-1866-40e0-a5ff-a6bf6675af4f
webhook-timestamp: 1674087231
webhook-signature-scheme: ed25519
webhook-signature: hnO3f9T8Ytu9HwrXslvumlUpqtNVqkhqw/enGzPCXe5BdqzCInXqYXFymVJaA7AZdpXwVLPo3mNl8EM+m7TBAg==

{
    "type": "message.received",
    "timestamp": "2022-11-03T20:26:10.344522Z",
    "text": "You've received a new message",
}

### References
https://www.standardwebhooks.com/
https://dev.twitch.tv/docs/eventsub/handling-webhook-events/#verifying-the-event-message

## Implementations

## Endnotes

#### 1 Out of Scope
There are many useful features of user messaging systems that we will not be adding to this protocol. We anticipate the development of more advanced and full-featured message protocols to fill these needs. Features that are considered out of scope for this protocol include:

- read receipts
- emojii responses
- typing indicators
- message replies (threading)
- multi-party (group) messages
- attachments