Webhook Configuration

Webhook Management

POST /api/organizations/:org_slug/webhooks

Create a new webhook for an organization. The webhook secret is generated automatically and returned only once upon creation.

Authentication: Required (Organization Management JWT)

Permissions: Organization owner or admin

Path Parameters:

Request Body:

Request Headers:

Authorization: Bearer {jwt_token}
Content-Type: application/json

Example Request:

curl -X POST https://sso.example.com/api/organizations/acme-corp/webhooks \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Webhook",
    "url": "https://api.acme.com/webhooks/sso",
    "events": [
      "user.login.success",
      "user.signup.success",
      "user.mfa.enabled"
    ]
  }'

Response (200 OK):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Production Webhook",
  "url": "https://api.acme.com/webhooks/sso",
  "events": [
    "user.login.success",
    "user.signup.success",
    "user.mfa.enabled"
  ],
  "is_active": true,
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:00Z"
}

Response Fields:

• id (string): Webhook unique identifier
• name (string): Webhook name
• url (string): Target URL
• events (array of strings): Subscribed event types
• is_active (boolean): Whether webhook is active
• created_at (string): ISO 8601 timestamp
• updated_at (string): ISO 8601 timestamp

Error Responses:

• 400 Bad Request: Invalid input (empty name/url, invalid URL format, invalid event types, duplicate name)

  {
    "error": "A webhook with this name already exists"
  }
  

  {
    "error": "Invalid event type: invalid.event. Valid types: user.login.success, ..."
  }
  

• 401 Unauthorized: Missing or invalid JWT token
• 403 Forbidden: User is not an admin or owner
• 404 Not Found: Organization not found

Important Notes:

• The webhook secret is generated automatically and must be stored securely for signature verification
• Webhook names must be unique within the organization
• At least one event type must be specified
• Invalid event types will return an error with the list of valid event types

GET /api/organizations/:org_slug/webhooks

List all webhooks configured for an organization.

Authentication: Required (Organization Management JWT)

Permissions: Organization owner or admin

Path Parameters:

Query Parameters: None

Request Headers:

Authorization: Bearer {jwt_token}

Example Request:

curl -X GET https://sso.example.com/api/organizations/acme-corp/webhooks \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Response (200 OK):

{
  "webhooks": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Production Webhook",
      "url": "https://api.acme.com/webhooks/sso",
      "events": ["user.login.success", "user.signup.success"],
      "is_active": true,
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T10:30:00Z"
    },
    {
      "id": "660e8400-e29b-41d4-a716-446655440111",
      "name": "Staging Webhook",
      "url": "https://staging-api.acme.com/webhooks/sso",
      "events": ["user.mfa.enabled", "user.mfa.disabled"],
      "is_active": false,
      "created_at": "2025-01-14T08:15:00Z",
      "updated_at": "2025-01-14T08:15:00Z"
    }
  ],
  "total": 2
}

Response Fields:

• webhooks (array): List of webhook objects
• total (integer): Total number of webhooks

Error Responses:

• 401 Unauthorized: Missing or invalid JWT token
• 403 Forbidden: User is not an admin or owner
• 404 Not Found: Organization not found

GET /api/organizations/:org_slug/webhooks/:webhook_id

Get details for a specific webhook.

Authentication: Required (Organization Management JWT)

Permissions: Organization owner or admin

Path Parameters:

Query Parameters: None

Request Headers:

Authorization: Bearer {jwt_token}

Example Request:

curl -X GET https://sso.example.com/api/organizations/acme-corp/webhooks/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Response (200 OK):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Production Webhook",
  "url": "https://api.acme.com/webhooks/sso",
  "events": ["user.login.success", "user.signup.success", "user.mfa.enabled"],
  "is_active": true,
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:00Z"
}

Error Responses:

• 401 Unauthorized: Missing or invalid JWT token
• 403 Forbidden: User is not an admin or owner
• 404 Not Found: Organization or webhook not found

PATCH /api/organizations/:org_slug/webhooks/:webhook_id

Update webhook configuration. All fields are optional - only provided fields will be updated.

Authentication: Required (Organization Management JWT)

Permissions: Organization owner or admin

Path Parameters:

Request Body:

Request Headers:

Authorization: Bearer {jwt_token}
Content-Type: application/json

Example Request:

curl -X PATCH https://sso.example.com/api/organizations/acme-corp/webhooks/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "is_active": false,
    "events": [
      "user.login.success",
      "user.signup.success",
      "user.mfa.enabled",
      "user.mfa.disabled"
    ]
  }'

Response (200 OK):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Production Webhook",
  "url": "https://api.acme.com/webhooks/sso",
  "events": [
    "user.login.success",
    "user.signup.success",
    "user.mfa.enabled",
    "user.mfa.disabled"
  ],
  "is_active": false,
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T12:45:00Z"
}

Error Responses:

• 400 Bad Request: Invalid input (empty name/url, invalid URL format, invalid event types, duplicate name)

  {
    "error": "A webhook with this name already exists"
  }
  

• 401 Unauthorized: Missing or invalid JWT token
• 403 Forbidden: User is not an admin or owner
• 404 Not Found: Organization or webhook not found

Notes:

• Only provided fields are updated
• Webhook name must be unique if changed
• At least one event must be specified if updating events
• Setting is_active: false disables the webhook without deleting delivery history

DELETE /api/organizations/:org_slug/webhooks/:webhook_id

Delete a webhook. This action is permanent and will also delete all delivery history.

Authentication: Required (Organization Management JWT)

Permissions: Organization owner or admin

Path Parameters:

Query Parameters: None

Request Headers:

Authorization: Bearer {jwt_token}

Example Request:

curl -X DELETE https://sso.example.com/api/organizations/acme-corp/webhooks/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Response: 200 OK with empty JSON object {}

Error Responses:

• 401 Unauthorized: Missing or invalid JWT token
• 403 Forbidden: User is not an admin or owner
• 404 Not Found: Organization or webhook not found

Warning: This action is irreversible. All delivery history associated with this webhook will be permanently deleted.