Create a webhook endpoint

POST

/v1/webhook-endpoints

const endpoint = await gp.webhookEndpoints.create({
  url: 'https://merchant.example/webhooks/gryphem',
  enabled_events: ['payment.confirmed', 'payment.review_required', 'payment.reorged'],
});
// endpoint.secret (whsec_…) is shown once — store it in your secret manager

• GRYPHEM PAY API

The whsec_… signing secret is returned once. Destinations are SSRF-checked at delivery time and redirects are never followed. Honors Idempotency-Key (replays return the original response for 24 h).

Authorizations

• ApiKey
• Session

Parameters

Header Parameters

Gryphem-Organization

string

Active organization for dashboard sessions. Ignored for API keys (the key determines the organization).

Gryphem-Environment

string

default: test

Allowed values: test live

test (default) or live for dashboard sessions. API keys determine the environment.

Idempotency-Key

string

<= 255 characters

Unique key per logical create operation (max 255 chars). Replays return the original response; reuse with a different body returns idempotency_error.

Request Body^required

Media typeapplication/json

object

url

required

string format: uri

<= 2048 characters

description

string

<= 200 characters

enabled_events

required

Array<string>

>= 1 items

store_id

string

Example ^generated

{
  "url": "https://example.com",
  "description": "example",
  "enabled_events": [
    "example"
  ],
  "store_id": "example"
}

Responses

201

Created; signing secret is shown once.

Media typeapplication/json

object

id

required

string

object

required

string

Allowed value: webhook_endpoint

livemode

required

boolean

url

required

string

description

required

string

enabled_events

required

Array

store_id

required

string | null

status

required

string

Allowed values: enabled disabled

secret_last4

required

string | null

secret_rotated_at

required

string | null format: date-time

created_at

required

string format: date-time

updated_at

required

string format: date-time

secret

required

Whsec_… signing secret, shown once.

string

Example

{
  "object": "webhook_endpoint",
  "enabled_events": [
    "payment_intent.created"
  ],
  "status": "enabled"
}

401

Missing or invalid credentials.

Media typeapplication/json

object

error

required

object

type

required

string

Allowed values: invalid_request_error authentication_error permission_error not_found_error conflict_error idempotency_error rate_limit_error feature_unavailable_error api_error

code

required

string

message

required

string

param

string

request_id

required

string

Example

{
  "error": {
    "type": "invalid_request_error"
  }
}

403

Authenticated but not permitted.

Media typeapplication/json

object

error

required

object

type

required

string

Allowed values: invalid_request_error authentication_error permission_error not_found_error conflict_error idempotency_error rate_limit_error feature_unavailable_error api_error

code

required

string

message

required

string

param

string

request_id

required

string

Example

{
  "error": {
    "type": "invalid_request_error"
  }
}

422

Validation failed.

Media typeapplication/json

object

error

required

object

type

required

string

Allowed values: invalid_request_error authentication_error permission_error not_found_error conflict_error idempotency_error rate_limit_error feature_unavailable_error api_error

code

required

string

message

required

string

param

string

request_id

required

string

Example

{
  "error": {
    "type": "invalid_request_error"
  }
}

429

Too many requests. See Retry-After.

Media typeapplication/json

object

error

required

object

type

required

string

Allowed values: invalid_request_error authentication_error permission_error not_found_error conflict_error idempotency_error rate_limit_error feature_unavailable_error api_error

code

required

string

message

required

string

param

string

request_id

required

string

Example

{
  "error": {
    "type": "invalid_request_error"
  }
}

Headers

Retry-After

integer