Skip to content
TimbroTimbroTimbro

Create a merchant webhook endpoint

POST
/webhook_endpoints
curl --request POST \
  --url https://api.timbro.dev/v1/webhook_endpoints \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'idempotency-key: example' \
  --data '{ "url": "https://example.com", "enabledEvents": [ "payment.succeeded" ] }'

Registers an HTTPS endpoint for signed domain events. The signing secret is returned only in this response.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
idempotency-key
required
string
>= 1 characters <= 255 characters /^[\x20-\x7e]+$/

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
CreateWebhookEndpointRequest
object
url
required

HTTPS endpoint that receives signed events.

string format: uri
enabledEvents
required
Array
>= 1 items <= 4 items unique items

Responses

Section titled “Responses”

201

Section titled “201”

The endpoint and its signing secret. Store the secret securely.

Media typeapplication/json
WebhookEndpointCreated

The endpoint and its signing secret. Store the secret securely.

object
id
required

Webhook endpoint identifier.

string
/^webhook_endpoint_[0-9a-hjkmnp-tv-z]{24,}$/
object
required
string
Allowed value: webhook_endpoint
url
required
string format: uri
enabledEvents
required
Array
>= 1 items
isEnabled
required
boolean
createdAt
required
string format: date-time
secret
required

Signing secret. Shown only at creation.

string
>= 1 characters
Example
{
  "object": "webhook_endpoint",
  "enabledEvents": [
    "payment.succeeded"
  ]
}

400

Section titled “400”

The request could not be understood or is not valid for this merchant account.

Media typeapplication/json
InvalidRequestError

The request could not be understood or is not valid for this merchant account.

object
error
required
object
type
required
string
Allowed value: invalid_request
code
required

Stable machine-readable code. Branch on this, never on message.

string
Allowed values: parameter_missing parameter_invalid provider_not_available currency_not_supported amount_below_minimum amount_above_maximum checkout_reference_invalid checkout_reference_expired fiscal_buyer_tax_id_invalid fiscal_line_total_invalid fiscal_lines_required payment_split_invalid
message
required

Human-readable. Wording may change; not a stable contract.

string
param

Dotted path to the offending request field.

string
docUrl
required
string format: uri
requestId
required

Correlation id, also returned as the Request-Id header.

string
/^request_[0-9a-hjkmnp-tv-z]{24,}$/
Example
{
  "error": {
    "type": "invalid_request",
    "code": "parameter_missing"
  }
}

401

Section titled “401”

The credential is missing, malformed, or no longer valid.

Media typeapplication/json
AuthenticationError

The credential is missing, malformed, or no longer valid.

object
error
required
object
type
required
string
Allowed value: authentication_error
code
required

Stable machine-readable code. Branch on this, never on message.

string
Allowed values: api_key_missing api_key_invalid checkout_token_invalid checkout_token_expired
message
required

Human-readable. Wording may change; not a stable contract.

string
param

Dotted path to the offending request field.

string
docUrl
required
string format: uri
requestId
required

Correlation id, also returned as the Request-Id header.

string
/^request_[0-9a-hjkmnp-tv-z]{24,}$/
Example
{
  "error": {
    "type": "authentication_error",
    "code": "api_key_missing"
  }
}

403

Section titled “403”

The credential is valid but not permitted to perform this operation on this resource.

Media typeapplication/json
PermissionError

The credential is valid but not permitted to perform this operation on this resource.

object
error
required
object
type
required
string
Allowed value: permission_error
code
required

Stable machine-readable code. Branch on this, never on message.

string
Allowed values: merchant_account_not_owned merchant_account_admin_required operation_not_permitted_for_checkout_token live_mode_not_enabled
message
required

Human-readable. Wording may change; not a stable contract.

string
param

Dotted path to the offending request field.

string
docUrl
required
string format: uri
requestId
required

Correlation id, also returned as the Request-Id header.

string
/^request_[0-9a-hjkmnp-tv-z]{24,}$/
Example
{
  "error": {
    "type": "permission_error",
    "code": "merchant_account_not_owned"
  }
}

404

Section titled “404”

No endpoint serves this method and path, or no resource with this identifier exists within the caller's tenant.

Media typeapplication/json
NotFoundError

No endpoint serves this method and path, or no resource with this identifier exists within the caller's tenant.

object
error
required
object
type
required
string
Allowed value: invalid_request
code
required

Stable machine-readable code. Branch on this, never on message.

string
Allowed values: endpoint_not_found payment_not_found fiscal_document_not_found merchant_account_not_found merchant_profile_not_found payment_split_not_found payment_part_not_found
message
required

Human-readable. Wording may change; not a stable contract.

string
param

Dotted path to the offending request field.

string
docUrl
required
string format: uri
requestId
required

Correlation id, also returned as the Request-Id header.

string
/^request_[0-9a-hjkmnp-tv-z]{24,}$/
Example
{
  "error": {
    "type": "invalid_request",
    "code": "endpoint_not_found"
  }
}

409

Section titled “409”

The request conflicts with the current state of the resource or with a previous request using the same Idempotency-Key.

Media typeapplication/json
ConflictError

The request conflicts with the current state of the resource or with a previous request using the same Idempotency-Key.

object
error
required
object
type
required
string
Allowed value: conflict_error
code
required

Stable machine-readable code. Branch on this, never on message.

string
Allowed values: idempotency_key_reused idempotency_request_in_progress idempotency_key_expired payment_method_already_in_progress payment_awaiting_verification decline_not_retryable checkout_window_closed fiscal_preset_locked payment_not_editable fiscal_buyer_required fiscal_correction_not_allowed payment_split_not_allowed payment_split_exists payment_split_locked payment_split_not_capturable payment_split_not_expired payment_split_not_renewable payment_split_complete payment_split_part_required payment_part_not_payable fiscal_artifact_not_ready
message
required

Human-readable. Wording may change; not a stable contract.

string
param

Dotted path to the offending request field.

string
docUrl
required
string format: uri
requestId
required

Correlation id, also returned as the Request-Id header.

string
/^request_[0-9a-hjkmnp-tv-z]{24,}$/
Example
{
  "error": {
    "type": "conflict_error",
    "code": "idempotency_key_reused"
  }
}

422

Section titled “422”

The request is well-formed but cannot be carried out for this payment or this merchant account.

Media typeapplication/json
UnprocessableRequestError

The request is well-formed but cannot be carried out for this payment or this merchant account.

object
error
required
object
type
required
string
Allowed value: invalid_request
code
required

Stable machine-readable code. Branch on this, never on message.

string
Allowed values: merchant_account_not_ready merchant_profile_incomplete payment_description_required merchant_account_provider_mismatch credential_storage_unavailable provider_not_eligible no_eligible_provider currency_not_supported_by_provider currency_not_supported_for_fiscal_document fiscal_total_mismatch fiscal_line_total_invalid fiscal_line_legal_tip_invalid fiscal_document_kind_not_allowed fiscal_document_kind_unsupported fiscal_government_eligibility_required fiscal_government_eligibility_not_allowed
message
required

Human-readable. Wording may change; not a stable contract.

string
param

Dotted path to the offending request field.

string
docUrl
required
string format: uri
requestId
required

Correlation id, also returned as the Request-Id header.

string
/^request_[0-9a-hjkmnp-tv-z]{24,}$/
Example
{
  "error": {
    "type": "invalid_request",
    "code": "merchant_account_not_ready"
  }
}

429

Section titled “429”

Too many requests. Retry after the interval in the Retry-After header.

Media typeapplication/json
RateLimitError

Too many requests. Retry after the interval in the Retry-After header.

object
error
required
object
type
required
string
Allowed value: rate_limit_error
code
required

Stable machine-readable code. Branch on this, never on message.

string
Allowed values: rate_limit_exceeded
message
required

Human-readable. Wording may change; not a stable contract.

string
param

Dotted path to the offending request field.

string
docUrl
required
string format: uri
requestId
required

Correlation id, also returned as the Request-Id header.

string
/^request_[0-9a-hjkmnp-tv-z]{24,}$/
Example
{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}

500

Section titled “500”

The gateway failed before reaching a payment outcome. Retry with the same Idempotency-Key.

Media typeapplication/json
ApiError

The gateway failed before reaching a payment outcome. Retry with the same Idempotency-Key.

object
error
required
object
type
required
string
Allowed value: api_error
code
required

Stable machine-readable code. Branch on this, never on message.

string
Allowed values: internal_error
message
required

Human-readable. Wording may change; not a stable contract.

string
param

Dotted path to the offending request field.

string
docUrl
required
string format: uri
requestId
required

Correlation id, also returned as the Request-Id header.

string
/^request_[0-9a-hjkmnp-tv-z]{24,}$/
Example
{
  "error": {
    "type": "api_error",
    "code": "internal_error"
  }
}

502

Section titled “502”

The payment provider rejected the request or could not be reached before anything was submitted. Safe to retry with the same Idempotency-Key.

Media typeapplication/json
ProviderError

The payment provider rejected the request or could not be reached before anything was submitted. Safe to retry with the same Idempotency-Key.

object
error
required
object
type
required
string
Allowed value: provider_error
code
required

Stable machine-readable code. Branch on this, never on message.

string
Allowed values: provider_unavailable provider_rejected_request
message
required

Human-readable. Wording may change; not a stable contract.

string
param

Dotted path to the offending request field.

string
docUrl
required
string format: uri
requestId
required

Correlation id, also returned as the Request-Id header.

string
/^request_[0-9a-hjkmnp-tv-z]{24,}$/
Example
{
  "error": {
    "type": "provider_error",
    "code": "provider_unavailable"
  }
}