Skip to main content
POST
/
v1
/
webhooks
Create Webhook
curl --request POST \
  --url https://api.monime.io/v1/webhooks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'Monime-Space-Id: <monime-space-id>' \
  --data '
{
  "name": "My Ecommerce Webhook",
  "url": "<string>",
  "apiRelease": "caph",
  "events": [
    "<string>"
  ],
  "enabled": true,
  "headers": {},
  "alertEmails": [
    "<string>"
  ],
  "verificationMethod": {
    "type": "HS256",
    "secret": "<string>"
  },
  "metadata": {}
}
'
{
  "success": true,
  "messages": [
    "<unknown>"
  ],
  "result": {
    "id": "<string>",
    "name": "My Ecommerce Webhook",
    "url": "<string>",
    "enabled": true,
    "events": [
      "<string>"
    ],
    "apiRelease": "caph",
    "verificationMethod": {
      "type": "HS256",
      "secret": "<string>"
    },
    "headers": {},
    "alertEmails": [
      "<string>"
    ],
    "createTime": "2023-11-07T05:31:56Z",
    "updateTime": "2023-11-07T05:31:56Z",
    "metadata": {}
  }
}

Authorizations

​
Authorization
string
header
required

Bearer HTTP authentication specified with the header Authorization: Bearer <access_token>

Headers

​
Idempotency-Key
string
required

This header is used to uniquely identify a logical request, ensuring that it is not processed more than once during retries. This header is used to uniquely identify a logical request, ensuring that it is not processed more than once during retries.

Maximum string length: 64
​
Monime-Version
enum<string> | null

Specifies which version of the Monime API will handle this request. Specifies which version of the Monime API will handle this request.

Available options:
caph.2025-08-23,
caph.2025-06-20
​
Monime-Space-Id
string
required

The value is the tenancy parameter that Monime uses to determine which space the request is intended for. The value is the tenancy parameter that Monime uses to determine which space the request is intended for.

Maximum string length: 64

Body

application/json

Create a new webhook with configuration for target URL, events, headers, and security.

​
name
string
required

Human-readable name for the webhook configuration.

Required string length: 1 - 100
Example:

"My Ecommerce Webhook"

​
url
string
required

Target URL that will receive webhook event payloads.

Maximum string length: 255
​
apiRelease
enum<string>
default:caph
required

Defines the target API release for this webhook. A release represents a stable snapshot of the API schema. Ensures the webhook receives the latest object schema for a given release cycle.

Available options:
caph,
siriusb
​
events
string[] | null
required

List of event types that should trigger this webhook.

Required array length: 1 - 100 elements
​
enabled
boolean
default:true

Flag indicating if the webhook should be active upon creation.

​
headers
object

Optional HTTP headers to include in outbound webhook requests.

​
alertEmails
string[] | null

Optional email addresses to notify on repeated delivery failures.

Maximum array length: 2
​
verificationMethod
HMAC SHA256 · object

Method to be use to verify the integrity of incoming webhook requests.

  • HMAC SHA256
  • ECDSA SHA256
​
metadata
object

Custom metadata for tagging or annotating this webhook.

Response

200 - application/json

OK

​
success
boolean

Represents the status of the query operation, confirming if it was successful. This field is always true

​
messages
any[]

Contains a list of messages providing relevant information or feedback related to the query or operation

​
result
Webhook · object

A Webhook is a user-defined HTTP endpoint that Monime invokes with a POST request whenever specific events occur, such as payment.completed or payout.failed.
Webhooks allow you to receive real-time notifications and integrate Monime’s event stream directly into your own systems.

Use Cases

  • Realtime Payment Updates
    Receive an immediate notification when a payment succeeds and update your user’s dashboard without polling the API.

  • Automated Payout Reconciliation
    Trigger accounting workflows or ERP system updates when a payout is marked as completed or failed.

  • Fraud & Risk Monitoring
    Stream payment events into your fraud detection system as they happen.