{"id":28280113,"url":"https://github.com/mtpontes/serverless-notification-service","last_synced_at":"2026-04-13T12:01:55.420Z","repository":{"id":288685239,"uuid":"968896886","full_name":"mtpontes/serverless-notification-service","owner":"mtpontes","description":"Highly extensible serverless notification service for different notification providers (Whatsapp, Discord, Telegram, local, etc)","archived":false,"fork":false,"pushed_at":"2025-11-11T01:51:38.000Z","size":1904,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-11-11T03:23:31.887Z","etag":null,"topics":["aws","aws-lambda","eventbridge","google-ca","notifications","python","serverless","sns","sns-topic","sqs","sqs-queue","terraform","terraform-module","whatsapp-api"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mtpontes.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-19T00:06:00.000Z","updated_at":"2025-11-11T01:51:42.000Z","dependencies_parsed_at":"2025-08-14T12:37:16.205Z","dependency_job_id":"74a2fe61-0e97-4024-8613-03bfb29955d6","html_url":"https://github.com/mtpontes/serverless-notification-service","commit_stats":null,"previous_names":["mtpontes/notification-service","mtpontes/serverless-notification-service"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/mtpontes/serverless-notification-service","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mtpontes%2Fserverless-notification-service","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mtpontes%2Fserverless-notification-service/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mtpontes%2Fserverless-notification-service/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mtpontes%2Fserverless-notification-service/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mtpontes","download_url":"https://codeload.github.com/mtpontes/serverless-notification-service/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mtpontes%2Fserverless-notification-service/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31751705,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-13T09:16:15.125Z","status":"ssl_error","status_checked_at":"2026-04-13T09:16:05.023Z","response_time":93,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","aws-lambda","eventbridge","google-ca","notifications","python","serverless","sns","sns-topic","sqs","sqs-queue","terraform","terraform-module","whatsapp-api"],"created_at":"2025-05-21T10:16:11.440Z","updated_at":"2026-04-13T12:01:55.413Z","avatar_url":"https://github.com/mtpontes.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Serverless Notification Service\n\nThis is a serverless notification system that is highly open to expansion.\n\nThe system is completely open to the inclusion of new notification providers. It is possible to integrate new notification providers without the need to make major adjustments to the base code. All you need to do is implement an interface and register it in the settings.\n\nIn addition, the notification is parameterized according to the preferences of each user registered in the database.\n\n## ☁️ System overview\n\n![application-schema](/assets/application.svg)\n\n## Tecnologies\n\n### Tools\n- Python 3.13\n- MongoDB\n- AWS S3\n- AWS Lambda\n- AWS Event Bridge\n- AWS SNS\n- AWS SQS\n\n### Optional tools\n- AWS Secret Manager: Used for provider Google Calendar, what a need for user credentials. The tool is optional as all provider is optional.\n\n### Infra \u0026 CI/CD\n- AWS\n- Terraform\n- Github Actions\n\n\u003cdetails\u003e\n    \u003csummary\u003e\u003ch2\u003eDetails\u003c/h2\u003e\u003c/summary\u003e\n\n### How it works\nA scheduler in Event Bridge is configured to periodically (e.g. daily) trigger an event that calls the `notification-publisher` Lambda function.\n\nThe `notification-publisher` service is responsible for fetching, filtering, and segregating notifications. It fetches notifications from MongoDB according to the defined filters, processes them, and then sends them to AWS SNS, with one message for each provider chosen by the user. It is possible to configure which providers will be used for a user from the `providers` attribute in the MongoDB database; this is a list of strings containing the names of the providers that will be used; the value of the strings must match the name of the providers registered in the system (`NotificationProviderEnum` enum class).\n\nSNS is a real-time messaging service that allows you to send and receive messages between different AWS services and third parties. In this system, the responsibility is to forward the messages to a queue in AWS SQS. When a new message enters the SQS queue, the `notification-dispatcher` Lambda is automatically triggered.\n\nThe `notification-dispatcher` Lambda is responsible for reading the message from the SQS queue and processing it to send a notification to the user using a specific notification provider selected by the user.\n\nBy default, the application already has integration with Google Calendar and Whatsapp. However, it is possible to add new notification providers by following the steps below.\n\n\n### Data Structures (models \u0026 MongoDB collections)\nFor the application to work, the following data structures are used in MongoDB:\n\n#### User:\n```python\nfull_name: str\nemail: str\nphone: str\nproviders: list[str]\n```\n\n#### Event:\n```python\ntitle: str\ndescription: str\ndt_init: datetime\ndt_end: datetime\nuser: User\n```\n\n### Adding new notification providers\nTo include new providers, changes are only required in the `dispatcher-service` system.\n\nStep by step:\n1. Implement the `NotificationProviderI` class,\n2. Create a new key for the new provider in the `NotificationProviderEnum` enum\n3. Add the new provider in the `load_notification_provider_registry` function.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003ch2\u003eHow to run\u003c/h2\u003e\u003c/summary\u003e\n\n### Prerequisites\n- AWS access key (third party service)\n- AWS CLI\n- Terraform\n\n### AWS Roles/Policies\n- AmazonEventBridgeFullAccess\n- AmazonS3FullAccess\n- AmazonSNSFullAccess\n- AmazonSQSFullAccess\n- AWSLambda_FullAccess\n- CloudWatchLogsFullAccess\n- iam:*\n\n\u003cdetails\u003e\n    \u003csummary\u003e\u003ch3\u003eEnvs\u003c/h3\u003e\u003c/summary\u003e\n\n#### Lambda - Publisher:\n```.env\n# Database\nDB_USERNAME\nDB_PASSWORD\nDB_NAME\nDB_PORT\nDB_URI\nDB_URI_ARGS # Opcional\n\n# AWS\nSNS_PATH\n```\n\n#### Lambda - Dispatcher:\n```.env\n# API token\nWHATSAPP_API_TOKEN\n```\n\n#### Pipeline vars/secrets:\n```\n# Vars\nREGION\nTFSTATE_BUCKET_NAME\n\n# Secrets\nAWS_ACCESS_KEY_ID\nAWS_SECRET_ACCESS_KEY\n\nDB_NAME\nDB_PASSWORD\nDB_PORT\nDB_URI\nDB_URI_ARGS\nDB_USERNAME\n\nWHATSAPP_API_TOKEN\n```\n\n#### Terraform envs:\n``` .env\nTF_LOG\nTF_VAR_publisher_source_code_zip\nTF_VAR_dispatcher_source_code_zip\nTF_VAR_publisher_source_code_lambda_s3_zip_name\nTF_VAR_dispatcher_source_code_lambda_s3_zip_name\nTF_VAR_region\nTF_VAR_tfstate_bucket_name\nTF_VAR_whatsapp_api_token\nTF_VAR_db_username\nTF_VAR_db_password\nTF_VAR_db_name\nTF_VAR_db_port\nTF_VAR_db_uri\nTF_VAR_db_uri_args\n```\n\u003c/details\u003e\n\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003ch3\u003eImplementation step by step\u003c/h3\u003e\u003c/summary\u003e\n\n\u003e **IMPORTANT** \\\n\u003e Configure all necessary envs (Terraform envs)\n\n#### Build\nGenerate an application zip along with all dependencies at the same level as the `` src`` directory.\n```bash\npython -m pip install --upgrade pip\nmkdir package\npip install -r requirements.txt -t package/\ncp -r src package/\ncp lambda_function.py package/\n\ncd package\nzip -r \"../source_code.zip\" . # Remember to assign the same name in the environment variable TF_VAR_code_result_zip\ncd ..\n```\n#### Terraform\n1. Create a bucket for the Terraform state file and set its name to the ``TF_VAR_tfstate_bucket_name`` environment variable\n\n2. Configure all environment variables\n\n3. Init\n    ```bash\n    terraform init \\\n        -backend-config=\"bucket=$TF_VAR_tfstate_bucket_name\" \\\n        -backend-config=\"key=terraform.state\" \\\n        -backend-config=\"region=$TF_VAR_region\"\n    ```\n\n4. Valide\n    ```terraform\n    terraform validate\n    ```\n\n5. Plan\n    ```terraform\n    terraform plan\n    ```\n\n6. Apply\n    ```terraform\n    terraform apply\n    ```\n\u003c/details\u003e\n\n\u003c/details\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmtpontes%2Fserverless-notification-service","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmtpontes%2Fserverless-notification-service","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmtpontes%2Fserverless-notification-service/lists"}