Crear un endpoint de webhook

POST

/v1/webhook-endpoints

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

• API de Timbro

Registra un endpoint HTTPS para eventos de dominio firmados. El secreto de firma se devuelve únicamente en esta respuesta.

Autenticación

• secretKey
• integrationToken
  invoices:test
• integrationToken
  invoices:live
• integrationToken
  payments:test
• integrationToken
  payments:live
• integrationToken
  refunds:test
• integrationToken
  refunds:live

Parámetros

Parámetros de cabecera

idempotency-key

obligatorio

string

>= 1 characters <= 255 characters /^[\x20-\x7e]+$/

Cuerpo de la solicitud^obligatorio

Media typeapplication/json

object

url

obligatorio

Endpoint HTTPS que recibe eventos firmados.

string format: uri

enabledEvents

obligatorio

Array

>= 1 items <= 17 items unique items

Respuestas

201

201

El endpoint y su nuevo secreto de firma. Guarda el secreto de forma segura.

Media typeapplication/json

Campos y códigos de la respuesta

El endpoint y su nuevo secreto de firma. Guarda el secreto de forma segura.

object

id

obligatorio

Identificador del endpoint de webhook.

string

/^webhook_endpoint_[0-9a-hjkmnp-tv-z]{24,}$/

object

obligatorio

string

Valor permitido: webhook_endpoint

url

obligatorio

string format: uri

enabledEvents

obligatorio

Configuración guardada de la suscripción, incluidos los tipos de eventos de contratos anteriores.

Array<string>

>= 1 items

status

obligatorio

Cualquiera de:

string

string

Valor permitido: active

string

string

Valor permitido: suspended

string

string

Valor permitido: deleted

secretCreatedAt

obligatorio

Cuándo se emitió el secreto de firma actual.

string format: date-time

previousSecretExpiresAt

obligatorio

Cualquiera de:

string

string format: date-time

null

null

createdAt

obligatorio

string format: date-time

secret

obligatorio

Secreto de firma en el formato whsec_ de Standard Webhooks. Solo se devuelve cuando se emite.

string

/^whsec_[A-Za-z0-9+/]+={0,2}$/

Cabeceras

request-id

obligatorio

string

Identifica esta solicitud. Indícalo cuando contactes a soporte.

Idempotent-Replayed

string

Valor permitido: true

true cuando esta respuesta repite el resultado guardado de una solicitud anterior con la misma clave de idempotencia (Idempotency-Key).

400

400

No se pudo entender la solicitud.

Media typeapplication/problem+json

Ejemplo

{
  "type": "about:blank",
  "title": "No se pudo entender la solicitud.",
  "status": 400,
  "code": "parameter_missing",
  "requestId": "request_000000000000000000000001"
}

Campos y códigos de la respuesta

Detalles de problema RFC 9457. Cada fallo de esta API es uno de estos objetos y cada operación limita code al subconjunto que puede emitir.

object

code

obligatorio

Código estable legible por máquinas. Toma decisiones con este código, nunca con title.

string

Valores permitidos: parameter_missing parameter_invalid request_body_malformed

requestId

obligatorio

string

status

obligatorio

integer format: int32

>= 400 <= 599

Valor permitido: 400

title

obligatorio

string

type

obligatorio

string

Valores permitidos: about:blank

Campos opcionales

detail

string

invoiceId

Solo aparece si la solicitud rechazada produjo una operación fiscal.

string

issuanceBlockers

Solo aparece cuando las reglas oficiales de emisión rechazan la emisión.

Array<string>

Valores permitidos: invalid_request unsupported_protocol unsupported_rules_version invalid_resolved_facts numbering_verifier_missing numbering_mode_not_enabled document_type_not_recognized sequence_missing sequence_not_observed_on_effective_date sequence_suspended sequence_cancelled sequence_superseded sequence_exhausted sequence_conflicting sequence_document_type_mismatch sequence_rejected_by_dgii sequence_expired sequence_range_overlap fiscal_number_capacity_exhausted invalid_fiscal_number fiscal_number_outside_authorized_range fiscal_number_before_verified_floor sequence_expiration_mismatch

problems

Solo aparece cuando el rechazo señala un valor incluido en la solicitud.

Array<object>

Un problema público estable del documento, guardado para una admisión rechazada.

object

code

obligatorio

string

message

obligatorio

string

path

obligatorio

string

Cabeceras

request-id

obligatorio

string

Identifica esta solicitud. Indícalo cuando contactes a soporte.

401

401

La credencial falta, tiene un formato incorrecto o ya no es válida.

Media typeapplication/problem+json

Ejemplo

{
  "type": "about:blank",
  "title": "La credencial falta, tiene un formato incorrecto o ya no es válida.",
  "status": 401,
  "code": "api_key_missing",
  "requestId": "request_000000000000000000000001"
}

Campos y códigos de la respuesta

Detalles de problema RFC 9457. Cada fallo de esta API es uno de estos objetos y cada operación limita code al subconjunto que puede emitir.

object

code

obligatorio

Código estable legible por máquinas. Toma decisiones con este código, nunca con title.

string

Valores permitidos: api_key_missing api_key_invalid integration_token_invalid checkout_token_invalid checkout_token_expired

requestId

obligatorio

string

status

obligatorio

integer format: int32

>= 400 <= 599

Valor permitido: 401

title

obligatorio

string

type

obligatorio

string

Valores permitidos: about:blank

Campos opcionales

detail

string

invoiceId

Solo aparece si la solicitud rechazada produjo una operación fiscal.

string

issuanceBlockers

Solo aparece cuando las reglas oficiales de emisión rechazan la emisión.

Array<string>

Valores permitidos: invalid_request unsupported_protocol unsupported_rules_version invalid_resolved_facts numbering_verifier_missing numbering_mode_not_enabled document_type_not_recognized sequence_missing sequence_not_observed_on_effective_date sequence_suspended sequence_cancelled sequence_superseded sequence_exhausted sequence_conflicting sequence_document_type_mismatch sequence_rejected_by_dgii sequence_expired sequence_range_overlap fiscal_number_capacity_exhausted invalid_fiscal_number fiscal_number_outside_authorized_range fiscal_number_before_verified_floor sequence_expiration_mismatch

problems

Solo aparece cuando el rechazo señala un valor incluido en la solicitud.

Array<object>

Un problema público estable del documento, guardado para una admisión rechazada.

object

code

obligatorio

string

message

obligatorio

string

path

obligatorio

string

Cabeceras

request-id

obligatorio

string

Identifica esta solicitud. Indícalo cuando contactes a soporte.

403

403

La credencial es válida, pero no tiene permiso para realizar esta operación.

Media typeapplication/problem+json

Ejemplo

{
  "type": "about:blank",
  "title": "La credencial es válida, pero no tiene permiso para realizar esta operación.",
  "status": 403,
  "code": "operation_not_permitted",
  "requestId": "request_000000000000000000000001"
}

Campos y códigos de la respuesta

Detalles de problema RFC 9457. Cada fallo de esta API es uno de estos objetos y cada operación limita code al subconjunto que puede emitir.

object

code

obligatorio

Código estable legible por máquinas. Toma decisiones con este código, nunca con title.

string

Valores permitidos: operation_not_permitted

requestId

obligatorio

string

status

obligatorio

integer format: int32

>= 400 <= 599

Valor permitido: 403

title

obligatorio

string

type

obligatorio

string

Valores permitidos: about:blank

Campos opcionales

detail

string

invoiceId

Solo aparece si la solicitud rechazada produjo una operación fiscal.

string

issuanceBlockers

Solo aparece cuando las reglas oficiales de emisión rechazan la emisión.

Array<string>

Valores permitidos: invalid_request unsupported_protocol unsupported_rules_version invalid_resolved_facts numbering_verifier_missing numbering_mode_not_enabled document_type_not_recognized sequence_missing sequence_not_observed_on_effective_date sequence_suspended sequence_cancelled sequence_superseded sequence_exhausted sequence_conflicting sequence_document_type_mismatch sequence_rejected_by_dgii sequence_expired sequence_range_overlap fiscal_number_capacity_exhausted invalid_fiscal_number fiscal_number_outside_authorized_range fiscal_number_before_verified_floor sequence_expiration_mismatch

problems

Solo aparece cuando el rechazo señala un valor incluido en la solicitud.

Array<object>

Un problema público estable del documento, guardado para una admisión rechazada.

object

code

obligatorio

string

message

obligatorio

string

path

obligatorio

string

Cabeceras

request-id

obligatorio

string

Identifica esta solicitud. Indícalo cuando contactes a soporte.

409

409

La solicitud entra en conflicto con el estado actual del recurso o con una solicitud anterior que usó la misma clave de idempotencia (Idempotency-Key).

Media typeapplication/problem+json

Ejemplo

{
  "type": "about:blank",
  "title": "La solicitud entra en conflicto con el estado actual del recurso o con una solicitud anterior que usó la misma clave de idempotencia (`Idempotency-Key`).",
  "status": 409,
  "code": "idempotency_key_reused",
  "requestId": "request_000000000000000000000001"
}

Campos y códigos de la respuesta

Detalles de problema RFC 9457. Cada fallo de esta API es uno de estos objetos y cada operación limita code al subconjunto que puede emitir.

object

code

obligatorio

Código estable legible por máquinas. Toma decisiones con este código, nunca con title.

string

Valores permitidos: idempotency_key_reused idempotency_request_in_progress idempotency_key_expired webhook_endpoint_deleted

requestId

obligatorio

string

status

obligatorio

integer format: int32

>= 400 <= 599

Valor permitido: 409

title

obligatorio

string

type

obligatorio

string

Valores permitidos: about:blank

Campos opcionales

detail

string

invoiceId

Solo aparece si la solicitud rechazada produjo una operación fiscal.

string

issuanceBlockers

Solo aparece cuando las reglas oficiales de emisión rechazan la emisión.

Array<string>

Valores permitidos: invalid_request unsupported_protocol unsupported_rules_version invalid_resolved_facts numbering_verifier_missing numbering_mode_not_enabled document_type_not_recognized sequence_missing sequence_not_observed_on_effective_date sequence_suspended sequence_cancelled sequence_superseded sequence_exhausted sequence_conflicting sequence_document_type_mismatch sequence_rejected_by_dgii sequence_expired sequence_range_overlap fiscal_number_capacity_exhausted invalid_fiscal_number fiscal_number_outside_authorized_range fiscal_number_before_verified_floor sequence_expiration_mismatch

problems

Solo aparece cuando el rechazo señala un valor incluido en la solicitud.

Array<object>

Un problema público estable del documento, guardado para una admisión rechazada.

object

code

obligatorio

string

message

obligatorio

string

path

obligatorio

string

Cabeceras

request-id

obligatorio

string

Identifica esta solicitud. Indícalo cuando contactes a soporte.

Retry-After

string

/^[0-9]+$/

Segundos que debes esperar antes de repetir esta solicitud o volver a consultar el recurso.

413

413

El cuerpo de la solicitud es más grande de lo que acepta este endpoint.

Media typeapplication/problem+json

Ejemplo

{
  "type": "about:blank",
  "title": "El cuerpo de la solicitud es más grande de lo que acepta este endpoint.",
  "status": 413,
  "code": "request_body_too_large",
  "requestId": "request_000000000000000000000001"
}

Campos y códigos de la respuesta

Detalles de problema RFC 9457. Cada fallo de esta API es uno de estos objetos y cada operación limita code al subconjunto que puede emitir.

object

code

obligatorio

Código estable legible por máquinas. Toma decisiones con este código, nunca con title.

string

Valores permitidos: request_body_too_large

requestId

obligatorio

string

status

obligatorio

integer format: int32

>= 400 <= 599

Valor permitido: 413

title

obligatorio

string

type

obligatorio

string

Valores permitidos: about:blank

Campos opcionales

detail

string

invoiceId

Solo aparece si la solicitud rechazada produjo una operación fiscal.

string

issuanceBlockers

Solo aparece cuando las reglas oficiales de emisión rechazan la emisión.

Array<string>

Valores permitidos: invalid_request unsupported_protocol unsupported_rules_version invalid_resolved_facts numbering_verifier_missing numbering_mode_not_enabled document_type_not_recognized sequence_missing sequence_not_observed_on_effective_date sequence_suspended sequence_cancelled sequence_superseded sequence_exhausted sequence_conflicting sequence_document_type_mismatch sequence_rejected_by_dgii sequence_expired sequence_range_overlap fiscal_number_capacity_exhausted invalid_fiscal_number fiscal_number_outside_authorized_range fiscal_number_before_verified_floor sequence_expiration_mismatch

problems

Solo aparece cuando el rechazo señala un valor incluido en la solicitud.

Array<object>

Un problema público estable del documento, guardado para una admisión rechazada.

object

code

obligatorio

string

message

obligatorio

string

path

obligatorio

string

Cabeceras

request-id

obligatorio

string

Identifica esta solicitud. Indícalo cuando contactes a soporte.

415

415

El cuerpo de la solicitud tiene un tipo de contenido que este endpoint no acepta.

Media typeapplication/problem+json

Ejemplo

{
  "type": "about:blank",
  "title": "El cuerpo de la solicitud tiene un tipo de contenido que este endpoint no acepta.",
  "status": 415,
  "code": "unsupported_media_type",
  "requestId": "request_000000000000000000000001"
}

Campos y códigos de la respuesta

Detalles de problema RFC 9457. Cada fallo de esta API es uno de estos objetos y cada operación limita code al subconjunto que puede emitir.

object

code

obligatorio

Código estable legible por máquinas. Toma decisiones con este código, nunca con title.

string

Valores permitidos: unsupported_media_type

requestId

obligatorio

string

status

obligatorio

integer format: int32

>= 400 <= 599

Valor permitido: 415

title

obligatorio

string

type

obligatorio

string

Valores permitidos: about:blank

Campos opcionales

detail

string

invoiceId

Solo aparece si la solicitud rechazada produjo una operación fiscal.

string

issuanceBlockers

Solo aparece cuando las reglas oficiales de emisión rechazan la emisión.

Array<string>

Valores permitidos: invalid_request unsupported_protocol unsupported_rules_version invalid_resolved_facts numbering_verifier_missing numbering_mode_not_enabled document_type_not_recognized sequence_missing sequence_not_observed_on_effective_date sequence_suspended sequence_cancelled sequence_superseded sequence_exhausted sequence_conflicting sequence_document_type_mismatch sequence_rejected_by_dgii sequence_expired sequence_range_overlap fiscal_number_capacity_exhausted invalid_fiscal_number fiscal_number_outside_authorized_range fiscal_number_before_verified_floor sequence_expiration_mismatch

problems

Solo aparece cuando el rechazo señala un valor incluido en la solicitud.

Array<object>

Un problema público estable del documento, guardado para una admisión rechazada.

object

code

obligatorio

string

message

obligatorio

string

path

obligatorio

string

Cabeceras

request-id

obligatorio

string

Identifica esta solicitud. Indícalo cuando contactes a soporte.

500

500

La solicitud no pudo completarse. Recupera el resultado con la referencia guardada o repite la solicitud con la misma clave de idempotencia.

Media typeapplication/problem+json

Ejemplo

{
  "type": "about:blank",
  "title": "La solicitud no pudo completarse. Recupera el resultado con la referencia guardada o repite la solicitud con la misma clave de idempotencia.",
  "status": 500,
  "code": "internal_error",
  "requestId": "request_000000000000000000000001"
}

Campos y códigos de la respuesta

Detalles de problema RFC 9457. Cada fallo de esta API es uno de estos objetos y cada operación limita code al subconjunto que puede emitir.

object

code

obligatorio

Código estable legible por máquinas. Toma decisiones con este código, nunca con title.

string

Valores permitidos: internal_error

requestId

obligatorio

string

status

obligatorio

integer format: int32

>= 400 <= 599

Valor permitido: 500

title

obligatorio

string

type

obligatorio

string

Valores permitidos: about:blank

Campos opcionales

detail

string

invoiceId

Solo aparece si la solicitud rechazada produjo una operación fiscal.

string

issuanceBlockers

Solo aparece cuando las reglas oficiales de emisión rechazan la emisión.

Array<string>

Valores permitidos: invalid_request unsupported_protocol unsupported_rules_version invalid_resolved_facts numbering_verifier_missing numbering_mode_not_enabled document_type_not_recognized sequence_missing sequence_not_observed_on_effective_date sequence_suspended sequence_cancelled sequence_superseded sequence_exhausted sequence_conflicting sequence_document_type_mismatch sequence_rejected_by_dgii sequence_expired sequence_range_overlap fiscal_number_capacity_exhausted invalid_fiscal_number fiscal_number_outside_authorized_range fiscal_number_before_verified_floor sequence_expiration_mismatch

problems

Solo aparece cuando el rechazo señala un valor incluido en la solicitud.

Array<object>

Un problema público estable del documento, guardado para una admisión rechazada.

object

code

obligatorio

string

message

obligatorio

string

path

obligatorio

string

Cabeceras

request-id

obligatorio

string

Identifica esta solicitud. Indícalo cuando contactes a soporte.

503

503

Un servicio requerido no está disponible temporalmente. Inténtalo de nuevo con la misma referencia o la misma clave de idempotencia.

Media typeapplication/problem+json

Ejemplo

{
  "type": "about:blank",
  "title": "Un servicio requerido no está disponible temporalmente. Inténtalo de nuevo con la misma referencia o la misma clave de idempotencia.",
  "status": 503,
  "code": "integration_authorization_unavailable",
  "requestId": "request_000000000000000000000001"
}

Campos y códigos de la respuesta

Detalles de problema RFC 9457. Cada fallo de esta API es uno de estos objetos y cada operación limita code al subconjunto que puede emitir.

object

code

obligatorio

Código estable legible por máquinas. Toma decisiones con este código, nunca con title.

string

Valores permitidos: integration_authorization_unavailable

requestId

obligatorio

string

status

obligatorio

integer format: int32

>= 400 <= 599

Valor permitido: 503

title

obligatorio

string

type

obligatorio

string

Valores permitidos: about:blank

Campos opcionales

detail

string

invoiceId

Solo aparece si la solicitud rechazada produjo una operación fiscal.

string

issuanceBlockers

Solo aparece cuando las reglas oficiales de emisión rechazan la emisión.

Array<string>

Valores permitidos: invalid_request unsupported_protocol unsupported_rules_version invalid_resolved_facts numbering_verifier_missing numbering_mode_not_enabled document_type_not_recognized sequence_missing sequence_not_observed_on_effective_date sequence_suspended sequence_cancelled sequence_superseded sequence_exhausted sequence_conflicting sequence_document_type_mismatch sequence_rejected_by_dgii sequence_expired sequence_range_overlap fiscal_number_capacity_exhausted invalid_fiscal_number fiscal_number_outside_authorized_range fiscal_number_before_verified_floor sequence_expiration_mismatch

problems

Solo aparece cuando el rechazo señala un valor incluido en la solicitud.

Array<object>

Un problema público estable del documento, guardado para una admisión rechazada.

object

code

obligatorio

string

message

obligatorio

string

path

obligatorio

string

Cabeceras

request-id

obligatorio

string

Identifica esta solicitud. Indícalo cuando contactes a soporte.

Retry-After

string

/^[0-9]+$/

Segundos que debes esperar antes de repetir esta solicitud o volver a consultar el recurso.