This project provides a webhook server for session.js. It serves two primary functions:

1. 🔌 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.
2. 📡 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.

• Session Webhook Server
  • 📚 Table of Contents
  • ✨ Features
  • 🤝 n8n Integration
  • 📋 Prerequisites
  • 🐳 Docker Deployment
  • 💻 Local Installation
  • ⚙️ Configuration
  • 📖 API Reference
    • 🔑 Authentication
    • 🔗 Endpoints
      • GET /status
      • POST /sendMessage
      • POST /sendAttachment
      • POST /deleteMessage
      • POST /setDisplayName
      • POST /setAvatar
      • POST /notifyScreenshot
      • POST /notifyMediaSaved
      • POST /addReaction
      • POST /removeReaction
  • 📨 Forwarded Events Reference
    • 📝 Event Structure
    • 📋 Event Types
  • 🤝 Contributing
  • 📜 License
  • ⚠️ Disclaimer

• 🌐 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.

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.

• Bun: For local installation. Installation guide.
• Docker & Docker Compose: For containerized deployment.

1. Clone the repository:

   git clone https://github.com/obeone/session-webhook-server.git
   cd session-webhook-server

2. Configure your environment: Create a .env file from the example. The docker-compose.yml file will automatically load it.

   cp .env.example .env

   Fill in the variables, especially SESSION_MNEMONIC and BEARER_TOKEN.

3. Build and run with Docker Compose:

   docker compose up --build -d

4. Check the status and logs:

   # Check container status
   docker compose ps
   
   # View logs in real-time
   docker compose logs -f session-webhook

5. To stop the server:

   docker compose down

   The session-data volume will persist your session storage, so you won't lose your identity.

1. Clone the repository:

   git clone https://github.com/obeone/session-webhook-server.git
   cd session-webhook-server

2. Install dependencies:

   bun install

3. Configure your environment: Copy the example environment file and edit it with your own values.

   cp .env.example .env

   See the Configuration section for details on each variable. You must provide a SESSION_MNEMONIC.

4. Run the server:

   • For production:

     bun start

   • For development (with auto-reloading):

     bun run dev

The server will be running on the port specified in your .env file (default: 8080).

The server is configured using environment variables. Create a .env file in the root directory to set them.

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>

Health check endpoint to verify that the server is running.

• Authentication: None

• Example Request:

  curl http://localhost:8080/status

• Success Response (200 OK):

  {
    "ok": true,
    "sessionId": "05xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "uptime": 123.456,
    "timestamp": "2023-10-27T10:00:00.000Z"
  }

Sends a text message to a Session ID.

• Request Body:

  {
    "to": "recipient_session_id",
    "text": "Hello from the webhook server!"
  }

• Example Request:

  curl -X POST http://localhost:8080/sendMessage \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <YOUR_BEARER_TOKEN>" \
    -d '{
          "to": "<RECIPIENT_SESSION_ID>",
          "text": "Hello, world!"
        }'

• Success Response (200 OK):

  {
    "success": true,
    "messageHash": "...",
    "syncMessageHash": "...",
    "timestamp": 1678886400000
  }

Sends a file attachment to a Session ID. The file data must be Base64 encoded.

• Request Body:

  {
    "to": "recipient_session_id",
    "filename": "image.jpg",
    "mimeType": "image/jpeg",
    "data": "base64_encoded_file_data"
  }

• Example Request:

  curl -X POST http://localhost:8080/sendAttachment \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <YOUR_BEARER_TOKEN>" \
    -d '{
          "to": "<RECIPIENT_SESSION_ID>",
          "filename": "test.txt",
          "mimeType": "text/plain",
          "data": "SGVsbG8sIFdvcmxkIQ=="
        }'

• Success Response (200 OK):

  {
    "success": true,
    "messageHash": "...",
    "syncMessageHash": "...",
    "timestamp": 1678886400000
  }

Deletes a previously sent message.

• Request Body:

  {
    "to": "recipient_session_id",
    "timestamp": 1678886400000,
    "hash": "message_hash"
  }

• Success Response (200 OK):

  {
    "success": true,
    "message": "Message deleted successfully"
  }

Updates the profile's display name.

• Request Body:

  {
    "displayName": "New Bot Name"
  }

• Success Response (200 OK):

  {
    "success": true,
    "message": "Display name updated successfully"
  }

Updates the profile's avatar. The image data must be Base64 encoded.

• Request Body:

  {
    "avatar": "base64_encoded_image_data"
  }

• Success Response (200 OK):

  {
    "success": true,
    "message": "Avatar updated successfully"
  }

Notifies a contact that a screenshot has been taken.

• Request Body:

  {
    "to": "recipient_session_id"
  }

• Success Response (200 OK):

  {
    "success": true,
    "message": "Screenshot notification sent"
  }

Notifies a contact that media from a message was saved.

• Request Body:

  {
    "to": "recipient_session_id",
    "timestamp": 1678886400000
  }

• Success Response (200 OK):

  {
    "success": true,
    "message": "Media saved notification sent"
  }

Adds a reaction to a specific message.

• Request Body:

  {
    "to": "recipient_session_id",
    "timestamp": 1678886400000,
    "emoji": "👍",
    "author": "author_session_id"
  }

• Success Response (200 OK):

  {
    "success": true,
    "message": "Reaction added"
  }

Removes a reaction from a specific message.

• Request Body:

  {
    "to": "recipient_session_id",
    "timestamp": 1678886400000,
    "emoji": "👍",
    "author": "author_session_id"
  }

• Success Response (200 OK):

  {
    "success": true,
    "message": "Reaction removed"
  }

The server listens for events from the Session client and forwards them as POST requests to the WEBHOOK_URL defined in your configuration.

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"
}

The following events are forwarded. The payload content is determined by the @session.js/client library.

Contributions are welcome! Please feel free to submit a pull request or open an issue to discuss your ideas.

1. Fork the repository.
2. Create a new branch (git checkout -b feature/your-feature-name).
3. Make your changes.
4. Commit your changes (git commit -m 'Add some feature').
5. Push to the branch (git push origin feature/your-feature-name).
6. Open a pull request.

This project is licensed under the MIT License. See the LICENSE file for details.

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.