Skip to content
Developer portal

Create a webhook endpoint

POST
/v1/webhook_endpoints
curl --request POST \
  --url https://api.example.com/v1/webhook_endpoints \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "url": "https://shop.example.com/webhooks", "enabled_events": [ "payment_intent.succeeded", "payment_intent.payment_failed" ] }'

The endpoint’s signing secret is returned on this response only: store it where your receiver can read it. The URL must be https:// and resolve only to public addresses; addresses on private networks are refused with validation_failure on url.

enabled_events takes the event types that are sent today, those listed in Webhooks without a Pending badge. A Pending type is refused with validation_failure until it ships, so a subscription is never accepted and then sent nothing. ["*"] subscribes to every type, including those added later; * stands alone and is refused beside named types.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
url
required
string format: uri
<= 2048 characters
enabled_events
required
Array<string>

Responses

Section titled “Responses”

201

Section titled “201”

The endpoint, with its secret.

Media typeapplication/json
object
id
string
object
string
Allowed value: webhook_endpoint
url
string format: uri
enabled_events
Array<string>
status
string
Allowed values: enabled disabled
secret

The signing secret, whsec_.... Returned on create and rotate only.

string
livemode
boolean
created

A Unix timestamp.

integer
Example
{
  "id": "we_3f9a1c2b7d4e5f60718293a4",
  "object": "webhook_endpoint",
  "status": "enabled"
}

400

Section titled “400”

validation_failure: invalid_parameter for a parameter missing or not valid, named in param; invalid_json for a body that is not JSON; unsupported_media_type for a body that is not sent as JSON; not_acceptable when the request will not accept JSON; method_not_allowed for an HTTP method the path does not take.

Media typeapplication/json
object
error
required
object
type
required
string
Allowed values: validation_failure authentication_failure authorization_failure not_found conflict timeout_or_in_progress policy_rejection invariant_violation rate_limited dependency_failure
code
required

A stable name for this refusal. Branch on this, never on message.

string
message
required

For the developer reading a log. May be reworded.

string
param
required

The field or parameter at fault, when there is one.

string | null
request_id
required
string | null
Example
{
  "error": {
    "type": "validation_failure",
    "code": "invalid_parameter",
    "message": "A whole number of minor units, from 1 to 999999999999999999.",
    "param": "amount",
    "request_id": "req_4f1c0b2e9a7d"
  }
}

401

Section titled “401”

authentication_failure: access_token_required when no token was sent, invalid_access_token when it is not valid, has expired, or is a client secret. Sent with a WWW-Authenticate: Bearer header, which adds error="invalid_token" when a token was sent.

Media typeapplication/json
object
error
required
object
type
required
string
Allowed values: validation_failure authentication_failure authorization_failure not_found conflict timeout_or_in_progress policy_rejection invariant_violation rate_limited dependency_failure
code
required

A stable name for this refusal. Branch on this, never on message.

string
message
required

For the developer reading a log. May be reworded.

string
param
required

The field or parameter at fault, when there is one.

string | null
request_id
required
string | null
Example
{
  "error": {
    "type": "validation_failure"
  }
}

403

Section titled “403”

authorization_failure with merchant_mismatch: a Merchant-Id header, query parameter or body field names a merchant or tenant other than the key’s.

Media typeapplication/json
object
error
required
object
type
required
string
Allowed values: validation_failure authentication_failure authorization_failure not_found conflict timeout_or_in_progress policy_rejection invariant_violation rate_limited dependency_failure
code
required

A stable name for this refusal. Branch on this, never on message.

string
message
required

For the developer reading a log. May be reworded.

string
param
required

The field or parameter at fault, when there is one.

string | null
request_id
required
string | null
Example
{
  "error": {
    "type": "validation_failure"
  }
}

404

Section titled “404”

not_found: resource_missing for an id this key cannot see, route_missing for a path that does not exist.

Media typeapplication/json
object
error
required
object
type
required
string
Allowed values: validation_failure authentication_failure authorization_failure not_found conflict timeout_or_in_progress policy_rejection invariant_violation rate_limited dependency_failure
code
required

A stable name for this refusal. Branch on this, never on message.

string
message
required

For the developer reading a log. May be reworded.

string
param
required

The field or parameter at fault, when there is one.

string | null
request_id
required
string | null
Example
{
  "error": {
    "type": "validation_failure"
  }
}

503

Section titled “503”

dependency_failure with service_unavailable: something on our side did not answer, or failed part-way. Whether the endpoint was created is not known, and its signing secret is shown only in the answer you did not get. This call takes no Idempotency-Key, so sending it again makes a second endpoint if the first was made. List your endpoints first with List webhook endpoints: if the endpoint is there, do not create another; rotate its secret to get a secret you can read, or disable it. If it is not, create it again.

Media typeapplication/json
object
error
required
object
type
required
string
Allowed values: validation_failure authentication_failure authorization_failure not_found conflict timeout_or_in_progress policy_rejection invariant_violation rate_limited dependency_failure
code
required

A stable name for this refusal. Branch on this, never on message.

string
message
required

For the developer reading a log. May be reworded.

string
param
required

The field or parameter at fault, when there is one.

string | null
request_id
required
string | null
Example
{
  "error": {
    "type": "validation_failure"
  }
}