Create webhook subscription

Add MCP server to your AI tool

Allow AI tools and LLMs to interact with the API documentation portal through MCP.

MCP server URL


        
          
            https://docs.staging.lumepay.com/mcp

Standard setup for AI tools providing an mcp.json file

{
  "Lumepay Staging API MCP server": {
    "url": "https://docs.staging.lumepay.com/mcp"
  }
}

POST /api/v1/webhooks/subscriptions

Creates a PENDING_VERIFICATION webhook subscription for a public HTTPS callback URL. Each API user may have only one non-deleted subscription for a given targetUrl.

Headers

X-API-KEY string Required

Public API key issued from the Lumepay API key management flow.
X-API-SECRET string Required

API secret paired with the public API key.

application/json

Body Required

name string

Optional customer label for the subscription.
targetUrl string Required

Public HTTPS callback URL. Private, loopback, link-local, metadata, and internal service destinations are rejected.
eventTypes array

Webhook event type.

At least 1 element.

Responses

201 application/json

Webhook subscription created successfully
Hide response attributes Show response attributes object
- id string
  
  Public webhook subscription id.
- name string
  
  Optional customer label.
- targetUrl string
  
  Public HTTPS callback URL.
- status string
  
  Subscription status. PENDING_VERIFICATION requires verify before activation. INACTIVE subscriptions receive no new deliveries. DISABLED subscriptions are not customer re-enabled in v1.
  
  Values are PENDING_VERIFICATION, ACTIVE, INACTIVE, or DISABLED.
- events array[object]
  
  Customer-facing webhook event catalog entry.
  
  Hide events attributes Show events attributes object
  
  Customer-facing webhook event catalog entry.
  
  eventType string
  
  Customer-facing event key used in subscription requests.
  
  resourceType string
  
  Resource category for the event.
  
  event string
  
  Event name within the resource category.
  
  displayName string
  
  Human-readable event name.
  
  description string
  
  Short description of when the event is emitted.
- verifiedAt string(date-time)
  
  UTC timestamp when the callback endpoint was last verified.
- createdAt string(date-time)
  
  UTC creation timestamp.
- updatedAt string(date-time)
  
  UTC last update timestamp.
400 application/json

Request validation failed
Hide response attributes Show response attributes object
- code integer(int32)
- message string
- httpStatus integer(int32)
- requestId string
- timestamp string(date-time)
- errors array[object]
  
  Hide errors attributes Show errors attributes object
  
  field string
  
  message string
429 application/json

Cloudflare API rate limit exceeded
Hide response attributes Show response attributes object
- error string
- message string
403 application/json

Authenticated API key is not allowed to perform this action
Hide response attributes Show response attributes object
- code integer(int32)
- message string
- httpStatus integer(int32)
- requestId string
- timestamp string(date-time)
- errors array[object]
  
  Hide errors attributes Show errors attributes object
  
  field string
  
  message string
500 application/json

Unexpected server error
Hide response attributes Show response attributes object
- code integer(int32)
- message string
- httpStatus integer(int32)
- requestId string
- timestamp string(date-time)
- errors array[object]
  
  Hide errors attributes Show errors attributes object
  
  field string
  
  message string
401 application/json

API key authentication failed
Hide response attributes Show response attributes object
- code integer(int32)
- message string
- httpStatus integer(int32)
- requestId string
- timestamp string(date-time)
- errors array[object]
  
  Hide errors attributes Show errors attributes object
  
  field string
  
  message string

POST /api/v1/webhooks/subscriptions

curl \
 --request POST 'https://api.staging.lumepay.com/api/v1/webhooks/subscriptions' \
 --header "Content-Type: application/json" \
 --header "X-API-KEY: string" \
 --header "X-API-SECRET: string" \
 --data '{"name":"Ops webhook alerts","targetUrl":"https://example.com/webhooks","eventTypes":["deposit.completed"]}'

Request examples

# Headers
X-API-KEY: string
X-API-SECRET: string

# Payload
{
  "name": "Ops webhook alerts",
  "targetUrl": "https://example.com/webhooks",
  "eventTypes": [
    "deposit.completed"
  ]
}

Response examples (201)

{
  "id": "whsub_5e737a5abaee46568bd8d530b9b3521a",
  "name": "Ops webhook alerts",
  "targetUrl": "https://example.com/webhooks",
  "status": "PENDING_VERIFICATION",
  "events": [
    {
      "eventType": "deposit.completed",
      "resourceType": "deposit",
      "event": "completed",
      "displayName": "Deposit completed",
      "description": "Deposit has completed."
    }
  ],
  "verifiedAt": "2026-06-12T15:03:23Z",
  "createdAt": "2026-06-12T15:01:00Z",
  "updatedAt": "2026-06-12T15:03:23Z"
}

Response examples (400)

{
  "httpStatus": 400,
  "requestId": "req_01HY0000000000000000000000",
  "message": "Request validation failed",
  "code": 400,
  "timestamp": "2026-01-01T00:00:00Z",
  "errors": []
}

Response examples (429)

{
  "error": "rate_limit_exceeded",
  "message": "API rate limit exceeded"
}

Response examples (403)

{
  "httpStatus": 403,
  "requestId": "req_01HY0000000000000000000000",
  "message": "Authenticated API key is not allowed to perform this action",
  "code": 403,
  "timestamp": "2026-01-01T00:00:00Z",
  "errors": []
}

Response examples (500)

{
  "httpStatus": 500,
  "requestId": "req_01HY0000000000000000000000",
  "message": "Unexpected server error",
  "code": 500,
  "timestamp": "2026-01-01T00:00:00Z",
  "errors": []
}

Response examples (401)

{
  "httpStatus": 401,
  "requestId": "req_01HY0000000000000000000000",
  "message": "API key authentication failed",
  "code": 401,
  "timestamp": "2026-01-01T00:00:00Z",
  "errors": []
}