Back to HomeDashboard →

API Reference

Complete REST API reference for Notifs. While we recommend using our official SDK, you can also integrate directly with our REST API.

Base URL

https://api.notifs.dev/v1

Authentication

All API requests require authentication via API key in the Authorization header:

Authorization: Bearer notifs_sk_your_api_key

Example Request

curl https://api.notifs.dev/v1/webhooks \
  -H "Authorization: Bearer notifs_sk_your_api_key"

Rate Limits

Rate limits are enforced per API key:

| Plan | Rate Limit | Header | |------|------------|--------| | Free | 10 req/sec | X-RateLimit-Limit: 10 | | Pro | 100 req/sec | X-RateLimit-Limit: 100 | | Enterprise | Custom | X-RateLimit-Limit: <custom> |

Rate Limit Headers

All responses include rate limit information:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

Webhooks

Send Webhook

Send a webhook notification to all configured channels.

Endpoint: POST /v1/webhooks/:webhookId/send

Parameters:

  • webhookId (path, required): The webhook ID

Request Body:

{
  "data": {
    "user": "john@example.com",
    "event": "payment_success",
    "amount": "$99.00"
  },
  "options": {
    "idempotencyKey": "payment_123",
    "metadata": {
      "userId": "user_456"
    }
  }
}

Response: 200 OK

{
  "id": "req_abc123",
  "webhookId": "webhook_xyz",
  "status": "queued",
  "createdAt": "2024-01-01T00:00:00Z"
}

Example:

curl -X POST https://api.notifs.dev/v1/webhooks/webhook_abc123/send \
  -H "Authorization: Bearer notifs_sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "user": "john@example.com",
      "event": "payment_success",
      "amount": "$99.00"
    }
  }'

Get Webhook

Retrieve webhook configuration.

Endpoint: GET /v1/webhooks/:webhookId

Response: 200 OK

{
  "id": "webhook_abc123",
  "name": "Payment Success",
  "channels": ["email", "slack"],
  "isActive": true,
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z"
}

Example:

curl https://api.notifs.dev/v1/webhooks/webhook_abc123 \
  -H "Authorization: Bearer notifs_sk_your_api_key"

List Webhooks

List all webhooks for your account.

Endpoint: GET /v1/webhooks

Query Parameters:

  • limit (optional): Number of results (default: 100, max: 100)
  • offset (optional): Pagination offset (default: 0)
  • active (optional): Filter by active status (true/false)

Response: 200 OK

{
  "data": [
    {
      "id": "webhook_abc123",
      "name": "Payment Success",
      "channels": ["email", "slack"],
      "isActive": true,
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ],
  "hasMore": false,
  "total": 1
}

Example:

curl "https://api.notifs.dev/v1/webhooks?limit=50&active=true" \
  -H "Authorization: Bearer notifs_sk_your_api_key"

Create Webhook

Create a new webhook.

Endpoint: POST /v1/webhooks

Request Body:

{
  "name": "Payment Success",
  "channels": ["email", "slack"],
  "template": {
    "email": {
      "subject": "Payment Received",
      "body": "Thank you {{user}}!"
    }
  }
}

Response: 201 Created

{
  "id": "webhook_abc123",
  "name": "Payment Success",
  "channels": ["email", "slack"],
  "secret": "whsec_...",
  "isActive": true,
  "createdAt": "2024-01-01T00:00:00Z"
}

Update Webhook

Update webhook configuration.

Endpoint: PATCH /v1/webhooks/:webhookId

Request Body:

{
  "name": "Payment Success - Updated",
  "isActive": false
}

Response: 200 OK

Delete Webhook

Delete a webhook permanently.

Endpoint: DELETE /v1/webhooks/:webhookId

Response: 204 No Content

Example:

curl -X DELETE https://api.notifs.dev/v1/webhooks/webhook_abc123 \
  -H "Authorization: Bearer notifs_sk_your_api_key"

Logs

List Logs

Retrieve webhook delivery logs.

Endpoint: GET /v1/logs

Query Parameters:

  • limit (optional): Number of results (default: 100)
  • offset (optional): Pagination offset
  • webhookId (optional): Filter by webhook ID
  • status (optional): Filter by status (queued, sent, failed)
  • startDate (optional): Filter logs after date (ISO 8601)
  • endDate (optional): Filter logs before date (ISO 8601)

Response: 200 OK

{
  "data": [
    {
      "id": "log_abc123",
      "webhookId": "webhook_xyz",
      "status": "sent",
      "payload": { "user": "john@example.com" },
      "response": { "statusCode": 200 },
      "duration": 125,
      "timestamp": "2024-01-01T00:00:00Z"
    }
  ],
  "hasMore": false,
  "total": 1
}

Example:

curl "https://api.notifs.dev/v1/logs?webhookId=webhook_abc123&status=failed" \
  -H "Authorization: Bearer notifs_sk_your_api_key"

Get Log

Get detailed log information.

Endpoint: GET /v1/logs/:logId

Response: 200 OK

{
  "id": "log_abc123",
  "webhookId": "webhook_xyz",
  "status": "sent",
  "payload": {
    "user": "john@example.com",
    "amount": "$99.00"
  },
  "response": {
    "statusCode": 200,
    "body": "OK"
  },
  "channels": {
    "email": {
      "status": "sent",
      "messageId": "msg_123"
    },
    "slack": {
      "status": "sent",
      "messageId": "ts_456"
    }
  },
  "duration": 125,
  "timestamp": "2024-01-01T00:00:00Z",
  "metadata": {
    "userId": "user_456"
  }
}

Channels

List Channels

List all available notification channels.

Endpoint: GET /v1/channels

Response: 200 OK

{
  "data": [
    {
      "id": "email",
      "name": "Email",
      "isConfigured": true,
      "provider": "mailgun"
    },
    {
      "id": "slack",
      "name": "Slack",
      "isConfigured": true
    },
    {
      "id": "sms",
      "name": "SMS",
      "isConfigured": false
    }
  ]
}

Configure Channel

Configure a notification channel.

Endpoint: POST /v1/channels/:channelId/configure

Request Body (Email):

{
  "provider": "mailgun",
  "apiKey": "key-...",
  "domain": "mail.yourapp.com",
  "fromEmail": "notifications@yourapp.com",
  "fromName": "Your App"
}

Request Body (Slack):

{
  "webhookUrl": "https://hooks.slack.com/services/...",
  "channel": "#notifications",
  "username": "Notifs Bot"
}

Response: 200 OK

Error Handling

All errors follow a consistent format:

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid webhook ID",
    "details": {
      "field": "webhookId",
      "issue": "Webhook not found"
    }
  }
}

Error Codes

| Code | Status | Description | |------|--------|-------------| | invalid_request | 400 | Request validation failed | | unauthorized | 401 | Invalid or missing API key | | forbidden | 403 | Insufficient permissions | | not_found | 404 | Resource not found | | rate_limit_exceeded | 429 | Rate limit exceeded | | internal_error | 500 | Internal server error |

Example Error Response

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please retry after 60 seconds.",
    "details": {
      "retryAfter": 60,
      "limit": 100,
      "remaining": 0
    }
  }
}

Idempotency

Prevent duplicate webhook sends by providing an idempotency key:

curl -X POST https://api.notifs.dev/v1/webhooks/webhook_abc123/send \
  -H "Authorization: Bearer notifs_sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "data": { "user": "john@example.com" },
    "options": {
      "idempotencyKey": "unique_key_123"
    }
  }'

Idempotency keys are valid for 24 hours. Requests with the same key return the cached response.

Webhooks Signatures

All webhook requests include an X-Notifs-Signature header with an HMAC-SHA256 signature. See the Security documentation for verification details.

Pagination

List endpoints support cursor-based pagination:

# First page
curl "https://api.notifs.dev/v1/webhooks?limit=50" \
  -H "Authorization: Bearer notifs_sk_your_api_key"

# Next page
curl "https://api.notifs.dev/v1/webhooks?limit=50&offset=50" \
  -H "Authorization: Bearer notifs_sk_your_api_key"

Response includes pagination metadata:

{
  "data": [...],
  "hasMore": true,
  "total": 150
}

Versioning

The API version is included in the URL path:

https://api.notifs.dev/v1/...

Breaking changes will result in a new version (v2, v3, etc.). We'll maintain support for older versions for at least 12 months.

SDKs

We recommend using our official SDKs instead of calling the REST API directly:

OpenAPI Specification

Download our OpenAPI 3.0 specification:

curl https://api.notifs.dev/openapi.json

Support

Next Steps