Skip to content
Hardcount
Run it locally
Pre-1.0 · one maintainer · Stripe and cards only · no SDKs (client libraries) yet · no production users yet. Docs describe v0.9.1 (29 Oct 2026) · What’s new →

Create webhook endpoint

POST
/v1/webhook-endpoints/endpoints
curl --request POST \
  --url http://localhost:8080/v1/webhook-endpoints/endpoints \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "url": "example", "description": "example", "events": [ "example" ] }'

Returns the endpoint plus its signing secret (shown once). Event names are validated against the emit catalog — subscribing to an event Hardcount never emits is a 422, not silence. Omitted/empty events = all events (“”); “invoice.”-style prefix wildcards are supported.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
Idempotency-Key
string

Makes the call safe to retry. Send a unique value (a UUID works) and the same value on every retry. For 24 hours, a repeat with the same key, method, path and body gets the first response again, with an Idempotent-Replayed: true header, instead of running again. The error cases are in docs/api-surface.md. The usage routes do not take it: each usage event carries its own idempotency_key.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
url
required
string
description
string
events
Array<string>

Example generated

{
  "url": "example",
  "description": "example",
  "events": [
    "example"
  ]
}

Responses

Section titled “Responses”

201

Section titled “201”

Endpoint created (response carries the one-time signing secret)

Media typeapplication/json

A new webhook endpoint and its signing secret. The secret is shown only here.

object
endpoint
required
object
id
required
string
tenant_id
string
livemode
required
boolean
url
required
string
description
string
secret_last4
required
string
events
required

Subscribed event types. * means all.

Array<string>
active
required

False = paused.

boolean
secondary_secret_last4

The previous signing secret, during a rotation grace period.

string
secondary_secret_expires_at
string format: date-time
created_at
required
string format: date-time
updated_at
required
string format: date-time
secret
required

The signing secret (whsec_…). Store it now; Hardcount does not show it again.

string

Example generated

{
  "endpoint": {
    "id": "example",
    "tenant_id": "example",
    "livemode": true,
    "url": "example",
    "description": "example",
    "secret_last4": "example",
    "events": [
      "example"
    ],
    "active": true,
    "secondary_secret_last4": "example",
    "secondary_secret_expires_at": "2026-04-15T12:00:00Z",
    "created_at": "2026-04-15T12:00:00Z",
    "updated_at": "2026-04-15T12:00:00Z"
  },
  "secret": "example"
}

422

Section titled “422”

Invalid URL or unknown event type