Session Webhook Server
This project provides a webhook server for session.js. It serves two primary functions:
- ๐ Exposes Webhook Endpoints: It allows you to control a Session client via a simple REST API to perform actions like sending messages, attachments, and managing profile details.
- ๐ก Forwards Session Events: It listens to all events from the Session client (like incoming messages, reactions, etc.) and forwards them to a pre-configured external webhook URL.
This makes it easy to integrate Session messaging capabilities into other applications, such as automation platforms (n8n, Zapier), custom bots, or backend services.
๐ Table of Contents
โจ Features
- ๐ RESTful API: Control Session actions with simple HTTP requests.
- ๐ก Event Forwarding: Get real-time notifications for all Session activity.
- ๐ Secure: Protect your API endpoints with a Bearer token.
- ๐พ Persistent Storage: Uses a file-based storage system to maintain the Session identity across restarts.
- ๐ Easy to Deploy: Run it locally with
bun or as a Docker container.
๐ค n8n Integration
This project is designed to work seamlessly with n8n-nodes-session, which provides custom nodes for integrating Session messaging directly into n8n workflows. The webhook server acts as a bridge between Session and n8n, enabling you to:
- ๐ฌ Send Session messages from n8n workflows
- ๐ Receive Session events as triggers in n8n
- ๐ค Build complex automation workflows with Session messaging capabilities
For complete n8n integration, install both this webhook server and the n8n-nodes-session package.
๐ Prerequisites
- Bun: For local installation. Installation guide.
- Docker & Docker Compose: For containerized deployment.
๐ณ Docker Deployment
-
Clone the repository:
git clone https://github.com/obeone/session-webhook-server.git
cd session-webhook-server
-
Configure your environment:
Create a .env file from the example. The docker-compose.yml file will automatically load it.
Fill in the variables, especially SESSION_MNEMONIC and BEARER_TOKEN.
-
Build and run with Docker Compose:
docker compose up --build -d
-
Check the status and logs:
# Check container status
docker compose ps
# View logs in real-time
docker compose logs -f session-webhook
-
To stop the server:
The session-data volume will persist your session storage, so you won't lose your identity.
๐ป Local Installation
-
Clone the repository:
git clone https://github.com/obeone/session-webhook-server.git
cd session-webhook-server
-
Install dependencies:
-
Configure your environment:
Copy the example environment file and edit it with your own values.
See the Configuration section for details on each variable. You must provide a SESSION_MNEMONIC.
-
Run the server:
The server will be running on the port specified in your .env file (default: 8080).
โ๏ธ Configuration
The server is configured using environment variables. Create a .env file in the root directory to set them.
| Variable |
Description |
Default Value |
Required |
PORT |
The port on which the server will listen. |
8080 |
No |
BEARER_TOKEN |
A secret token to authorize API requests. |
your-secure-bearer-token-here |
Yes |
WEBHOOK_URL |
The external URL to which Session events will be forwarded. |
https://example.com/hook |
Yes |
SESSION_MNEMONIC |
The 13-word recovery phrase for your Session account. |
(none) |
Yes |
SESSION_DISPLAY_NAME |
The display name for the Session bot. |
Session Webhook Bot |
No |
STORAGE_FILE |
Path to the file for persistent session storage. |
./session-storage.db |
No |
LOG_LEVEL |
The logging level (error, warn, info, http, verbose, debug). |
info |
No |
๐ API Reference
๐ Authentication
All endpoints (except /status) are protected. You must provide the Bearer token in the Authorization header with every request.
Example: Authorization: Bearer <YOUR_BEARER_TOKEN>
๐ Endpoints
GET /status
Health check endpoint to verify that the server is running.
POST /sendMessage
Sends a text message to a Session ID.
POST /sendAttachment
Sends a file attachment to a Session ID. The file data must be Base64 encoded.
POST /deleteMessage
Deletes a previously sent message.
POST /setDisplayName
Updates the profile's display name.
POST /setAvatar
Updates the profile's avatar. The image data must be Base64 encoded.
POST /notifyScreenshot
Notifies a contact that a screenshot has been taken.
POST /notifyMediaSaved
Notifies a contact that media from a message was saved.
POST /addReaction
Adds a reaction to a specific message.
POST /removeReaction
Removes a reaction from a specific message.
๐จ Forwarded Events Reference
The server listens for events from the Session client and forwards them as POST requests to the WEBHOOK_URL defined in your configuration.
๐ Event Structure
All forwarded events have the following JSON structure:
{
"event": "eventName",
"payload": {
// Payload content depends on the event type
},
"timestamp": "2023-10-27T10:00:00.000Z"
}
๐ Event Types
The following events are forwarded. The payload content is determined by the @session.js/client library.
| Event Name |
Description |
message |
A new message is received. |
syncMessage |
A message from another linked device is synced. |
syncDisplayName |
A contact's display name has changed. |
syncAvatar |
A contact's avatar has changed. |
messageDeleted |
A message was deleted by the sender. |
messageRead |
A sent message has been marked as read by the recipient. |
messageTypingIndicator |
A contact is typing a message. |
screenshotTaken |
A contact has taken a screenshot of the conversation. |
mediaSaved |
A contact has saved media from a message. |
messageRequestApproved |
A contact has accepted your message request. |
call |
An incoming or outgoing call event has occurred. |
reactionAdded |
A reaction was added to one of your messages. |
reactionRemoved |
A reaction was removed from one of your messages. |
๐ค Contributing
Contributions are welcome! Please feel free to submit a pull request or open an issue to discuss your ideas.
- Fork the repository.
- Create a new branch (
git checkout -b feature/your-feature-name).
- Make your changes.
- Commit your changes (
git commit -m 'Add some feature').
- Push to the branch (
git push origin feature/your-feature-name).
- Open a pull request.
๐ License
This project is licensed under the MIT License. See the LICENSE file for details.
โ ๏ธ Disclaimer
This project is an unofficial tool and is not affiliated with, endorsed by, or in any way officially connected with the Session project or the Oxen Privacy Tech Foundation. Use it at your own risk. The use of a client's recovery phrase should be handled with extreme care.