openwebhooks-api

README

OpenWebhooks API

The open-source infrastructure for reliable webhook delivery

What is OpenWebhooks?

OpenWebhooks is an open-source infrastructure for delivering webhooks reliably and securely.

It’s designed for developers and teams who want full control over how events are delivered across systems — whether internal or external — without depending on external services. OpenWebhooks acts as the trusted layer between your system and any destination that needs to react to changes in real time.

Why OpenWebhooks?

Delivering webhooks reliably and securely is complex and often underestimated. OpenWebhooks removes this burden by providing a production-ready solution that handles retries, failure management, and security, so developers can focus on building their core products.

Webhook delivery is prone to issues like unreliable endpoints, timeouts, and data loss. OpenWebhooks mitigates this by persisting messages, automatically retrying failed deliveries with backoff, and keeping detailed records of delivery attempts for auditing.

Security is built-in from the start. OpenWebhooks supports HMAC signing, replay protection, and SSRF-safe delivery to user-supplied endpoints. It enforces strict outbound request policies to protect your infrastructure from abuse.

Unlike third-party SaaS services, OpenWebhooks is fully open-source and self-hosted, giving you complete control over your webhook infrastructure, data, and compliance requirements—all with a simple, developer-friendly API.

Get Started

Run OpenWebhooks locally in just a few steps:

git clone https://github.com/openwebhooks/openwebhooks-api.git

cd openwebhooks-api

make

CONNECTION_STRING="mongodb://localhost:27017/" ./bin/server

Once running, your API will be available at http://localhost:8080

Endpoints

Create Application

Request

curl -X "POST" "https://api.openwebhooks.dev/api/v1/application" \
  -H "Content-Type: application/json" \
  -d '{
    "uid": "application-001",
    "name": "Application 001",
    "metadata": {
      "type": "internal"
    }
  }'

Response

{
  "id": "app_504da47b-9c9c-4447-bbdb-a4355e5e3530",
  "uid": "application-001",
  "name": "Application 001",
  "secrets": [
    {
      "value": "key_5c343c6c-8279-4276-a000-6a662cda358f",
      "valid_from_timestamp": "2025-07-11T07:41:27.772Z",
      "valid_until_timestamp": "2025-10-09T07:41:27.772Z"
    }
  ],
  "created_at": "2025-07-11T07:41:27.772Z",
  "updated_at": "2025-07-11T07:41:27.772Z",
  "metadata": { "type": "internal" }
}

Create Endpoint

Request

curl -X "POST" "https://api.openwebhooks.dev/api/v1/application/YOUR_APPLICATION_UID/endpoints" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_APPLICATION_SECRET" \
  -d '{
    "uid": "endpoint-001",
    "description": "Endpoint 001",
    "url": "https://webhook.site/5b197c0f-5490-4b18-8498-bbfe25a05561",
    "disabled": false,
    "event_types": ["charge.succeeded"],
    "channels": ["charge"],
    "metadata": {
      "hello": "world"
    }
  }'

Response

{
  "id": "ep_d43964b4-299a-4598-9902-ef7d92d80d44",
  "uid": "endpoint-001",
  "description": "Production 001",
  "url": "https://webhook.site/5b197c0f-5490-4b18-8498-bbfe25a05561",
  "disabled": false,
  "event_types": ["charge.succeeded"],
  "channels": ["charge"],
  "secrets": [
    {
      "value": "whsec_l3QZowgsrw6xPCq83Hksfgw0ZxwYOBJbY2UUV4yW/fc=",
      "valid_from_timestamp": "2025-07-11T07:48:53.932Z",
      "valid_until_timestamp": "2025-10-09T07:48:53.932Z"
    }
  ],
  "created_at": "2025-07-11T07:48:53.932Z",
  "updated_at": "2025-07-11T07:48:53.932Z",
  "metadata": { "hello": "world" }
}

Create Message

Request

curl -X "POST" "https://api.openwebhooks.dev/api/v1/application/YOUR_APPLICATION_UID/messages" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_APPLICATION_SECRET" \
  -d '{
    "event_id": "event-001",
    "event_type": "charge.succeeded",
    "payload": {
      "amount": 1099
    },
    "channels": ["charge"],
    "tags": []
  }'

Response

{
  "id": "msg_b71c53bb-9385-483d-8eab-da1b9c85a52b",
  "event_id": "event-001",
  "event_type": "charge.succeeded",
  "payload": { "amount": 1099 },
  "channels": ["charge"],
  "tags": [],
  "timestamp": "2025-07-11T07:52:15.491Z"
}

Contributing

Contributions are welcome!

If you have ideas for improvements, find a security issue, or want to add new features, feel free to open an issue or submit a pull request.

License

This project is licensed under the MIT License.