Skip to main content
POST
Create a new webhook
Creates a webhook endpoint for receiving events. Only OWNERS and ADMINS can create webhooks.

Authentication

This endpoint requires authentication via Bearer token:
  • Authorization: Bearer <token>

Path Parameters

Request Body

Environments

Each webhook belongs to one environment, production or sandbox. The environment decides which invoice events it receives:
  • A sandbox invoice only reaches sandbox webhooks.
  • A production invoice only reaches production webhooks.
This rule only applies to invoice.* events. All other events (organization.*, member.*, invite.*, certificate.*, and so on) reach every webhook subscribed to them, whatever its environment. The test event sent by POST /webhooks/{id}/test is not filtered either. The environment cannot be changed once the webhook exists. To receive events from the other environment, create a new webhook.

Available Events

Subscribe to any of these events:
  • Organization: organization.updated
  • Members: member.added, member.removed, member.role_updated
  • Invites: invite.created, invite.accepted, invite.cancelled
  • Invoices (CFDI): invoice.stamped, invoice.cancelled, invoice.cancellation_pending, invoice.cancellation_rejected, invoice.stamping_failed, invoice.payment_received
  • Certificates (CSD): certificate.uploaded, certificate.expiring, certificate.expired, certificate.deleted
  • Trial: trial.ending_soon, trial.expired, trial.converted
  • API: rate_limit.exceeded

Permissions

Only OWNERS and ADMINS can create webhooks.

Example Request

Example Response

⚠️ Important: Save the secret value - it’s only returned once and used for signature verification.

Webhook Payload

Each delivery is a POST to your URL. The body is the event payload itself, as JSON, with no wrapper: there is no event, organization or data field around it. Each event’s payload is shown in Webhook Event Payloads. The event type is only sent in the X-Webhook-Event header. Read it from there to decide how to handle the delivery. For example, an invoice.cancelled delivery looks like this:
A handler that routes by event type reads the header, not the body:
The organization is not part of the payload (except in member.role_updated). Each webhook belongs to one organization, so use the webhook’s URL or secret to know which organization a delivery is for.

Signature Verification

All webhook requests include an HMAC SHA-256 signature in the X-Webhook-Signature header for verification. The header has the format sha256=<hex>, and the signature is computed over the raw request body, before you parse it as JSON. If you parse and re-serialize the body, the signature will not match.
The signature does not cover the X-Webhook-Timestamp header, so it cannot detect replays. Deduplicate deliveries by X-Webhook-ID: a retry of the same delivery keeps the same id, so store the ids you have already processed and ignore repeats. See the PHP SDK for a Laravel controller example.

Webhook Event Payloads

Each example below is the full request body for that event.
organization.updated, member.added, member.removed, invite.created, invite.accepted and invite.cancelled can be subscribed to, but Timbrix does not send them yet. A webhook subscribed only to them receives no deliveries.

Test event

POST /webhooks/{id}/test sends this body. X-Webhook-Event carries the first event the webhook is subscribed to, so check test before handling the delivery as a real event.

invoice.stamped

Sent when a CFDI has been successfully stamped by the PAC.
relatedCfdis is empty for a regular invoice. A substitute CFDI carries [{ "type": "04", "uuids": ["<UUID original>"] }]. channel indica desde dónde se creó el CFDI (ver X-Timbrix-Client); null si no se registró.

invoice.cancelled

Sent when a CFDI has been cancelled (directly or after receiver acceptance).

invoice.cancellation_pending

Sent when a CFDI cancellation request requires receiver approval (per SAT eligibility rules) instead of resolving directly. The receiver has until respondBy to accept or reject it through the SAT portal — the CFDI remains vigente until then.

invoice.cancellation_rejected

Sent when a receiver rejects a pending CFDI cancellation request. The CFDI remains vigente.

invoice.stamping_failed

Sent when CFDI stamping failed at the PAC. errorCode is PAC_STAMP_FAILED_CONFIRMED when Timbrix confirmed with the PAC that a previously unconfirmed stamp was not issued.

invoice.payment_received

Sent once per Complemento de Pago (CFDI type P) stamped for PPD invoices. invoice.stamped is also sent for the same CFDI with tipoComprobante: "P". documents lists every invoice the payment settles, with its installment number and balances.

certificate.uploaded

Sent when a CSD is uploaded. replaced is true when it replaced an existing CSD (rotation), and previousSerialNumber holds the old serial. Re-uploading the same CSD also reports replaced: true, with previousSerialNumber equal to serialNumber. rfc may be null if the organization has no legal data on file.

certificate.expiring

Sent once per threshold, 30, 7 and 1 days before the CSD expires (checked daily at 9:00 Mexico City time). daysUntilExpiration counts full days remaining. If several thresholds were crossed since the last check, only the closest one is sent. Uploading a new CSD resets the alerts. daysUntilExpiration can be lower than threshold (for example threshold: 1 with daysUntilExpiration: 0 when it expires later the same day, or when a CSD is uploaded that is already within 30 days of expiring). rfc may be null if the organization has no legal data on file.

certificate.expired

Sent once when the CSD has expired. From this point stamping fails until a new CSD is uploaded. rfc may be null if the organization has no legal data on file.

certificate.deleted

Sent when the organization’s CSD is deleted. Stamping fails until a new one is uploaded. rfc may be null if the organization has no legal data on file.

trial.ending_soon

Sent once when 3 days or less remain in the organization’s free trial. daysRemaining is rounded up (1–3).

trial.expired

Sent once when the trial ended without a paid plan and access was locked. expiredAt is when the lock was applied.

trial.converted

Sent once when a trial organization subscribes to a paid plan. afterExpiration is true when the payment happened after the trial had already ended.
There is no trial.started event: the trial begins the moment the organization is created, before any webhook can be registered. Read the trial dates from GET /organizations/{id} instead.

rate_limit.exceeded

Sent when one of your API keys exceeds a rate limit and gets a 429. Sent at most once per hour per organization. scope is organization when the plan limit was reached, or api_key when the key’s own lower limit was reached. window is minute or hour.

member.role_updated

Sent when a member’s role changes, either by a normal role update or by a transfer of ownership. A transfer sends two events: one for the new owner and one for the previous owner (who becomes an admin). userId is the member whose role changed and updatedBy is the user who made the change.

Retry Logic

A delivery succeeds when your endpoint responds with a 2xx status within 30 seconds. Otherwise Timbrix tries again, up to 3 attempts in total (the first delivery plus 2 retries). Pending retries are checked every minute: the second attempt happens at least 1 minute after the event, and the third at least 2 minutes after. If the third attempt also fails, the delivery is marked as failed.

Common Errors

400 Bad Request

Invalid input data.

401 Unauthorized

Authentication required.

403 Forbidden

Only owners and admins can create webhooks.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

organizationId
string
required

Body

application/json
url
string
required

Webhook endpoint URL

Example:

"https://example.com/webhooks"

events
enum<string>[]
required

Events to subscribe to

Available options:
organization.updated,
member.added,
member.removed,
member.role_updated,
invite.created,
invite.accepted,
invite.cancelled,
webhook.created,
invoice.stamped,
invoice.cancelled,
invoice.cancellation_pending,
invoice.cancellation_rejected,
invoice.stamping_failed,
invoice.payment_received,
certificate.uploaded,
certificate.expiring,
certificate.expired,
certificate.deleted,
trial.ending_soon,
trial.expired,
trial.converted
Example:
environment
enum<string>
default:production

Environment whose invoice.* events this webhook receives. Immutable after creation. Defaults to production.

Available options:
production,
sandbox

Response

Webhook created successfully. Returns webhook configuration with signing secret.