Skip to content

Webhooks

Receiving events at a URL: verifying the signature, discarding duplicates, and reconciling with the event stream.

POST /v1/webhook_endpoints (permission webhooks:write; Idempotency-Key required) creates a destination (at most 20 per organization; the test and the live half have their own). Its signing secret is in that answer and nowhere else, ever: store it then. If it is lost, rotate it.

What arrives

A POST with a JSON body, the public envelope of the event: id, type, created_at, mode, organization_id, data, and simulated: true only for an event fabricated in test mode. GET /v1/event_types shows an example of every type.

Verify every message (Standard Webhooks)

Three headers travel with it: webhook-id, webhook-timestamp (seconds) and webhook-signature.

  • The signed content is <webhook-id>.<webhook-timestamp>.<body>, with the body EXACTLY as received (the raw bytes, before any JSON parsing).
  • The signature is v1,<base64 of HMAC-SHA256(signed content, key)>, where the key is the standard-base64 decoding of the secret after its whsec_ prefix.
  • webhook-signature may hold several signatures separated by a space (during a rotation): accept the message if ANY matches. Compare in constant time.
  • Reject a message whose timestamp is more than a few minutes away from now: it is a replay. Use a standardwebhooks library instead of writing this by hand; the signatures of this API are proven against the official one.

Discard duplicates by webhook-id

Delivery is at-least-once: a retry, and a resend you ask for, carry the SAME webhook-id (the id of the event). Keep the ids you processed and answer 2xx to one you already have. Answer fast and do the work afterwards: a slow answer counts as a failure and is retried.

Reconcile with the event stream

A webhook can be lost while your receiver is down. The truth is the event stream: GET /v1/events (permission events:read) by cursor returns everything in order, including what no webhook delivered. A receiver that stores the last cursor it reconciled never misses an event.

Looking at what happened

  • POST /v1/webhook_endpoints/{id}/test sends a signed sample now and answers what your receiver said.
  • GET /v1/webhook_endpoints/{id}/deliveries is the delivery log of a destination.
  • GET /v1/events/{id}/deliveries says where one event went; POST /v1/events/{id}/resend sends it again.
  • POST /v1/webhook_endpoints/{id}/rotate_secret makes a new secret; the previous one keeps signing for a while, so both verify during the change.
  • In a test organization, POST /v1/test/events fabricates an event to exercise your receiver. It is marked simulated.

A destination that keeps failing is disabled by the service (event webhook_endpoint.disabled), and the administrators are told by email.

Event types

Type Subject What happened Alerts the administrators
organization.created organization An organization and its test twin were created.
organization.updated organization The name of the organization changed.
organization.archived organization The organization was archived.
member.added member A person became a member.
member.updated member The role of a member changed.
member.removed member A membership ended. Carries the membership as it was, and by: self when the person left the organization, member when another member removed them.
service_account.created service_account A service account was created.
service_account.updated service_account The name or the scopes of a service account changed.
service_account.disabled service_account A service account was disabled; all its keys stopped working.
api_key.created api_key A key was created. The secret is never in the event.
api_key.revoked api_key A key was revoked. Carries the key as it was, without its secret.
issuer.created issuer The fiscal data of the issuer was set for the first time.
issuer.updated issuer The fiscal data of the issuer changed.
series.created series A series was created.
series.updated series A series was deactivated, reactivated or moved its next number forward. Carries the previous and the new value of each field that changed.
invoice.created invoice An invoice was accepted by the API and took its number. It is not yet sent.
invoice.sent invoice The provider received the invoice; SUNAT has not answered yet.
invoice.accepted invoice SUNAT accepted the invoice.
invoice.rejected invoice SUNAT rejected the invoice. Its number was not used. yes
invoice.failed invoice The invoice cannot go on by itself and needs a correction. yes
invoice.stalled invoice The invoice has been in process longer than expected. Nothing is lost; someone should look. yes
invoice.held invoice The provider gave an answer the service cannot interpret. The invoice is held in process: nothing is resent, and the staff of the service was told.
invoice.released invoice The staff of the service released a held invoice: it first asks the provider, then goes on.
production_access.requested production_access The organization asked to enter the production access list.
production_access.accepted production_access The staff accepted the organization on the production access list: it can send its activation request.
production_access.rejected production_access The staff rejected the access request, with its reason.
production_access.revoked production_access The staff revoked the access of the organization; an activation request in progress was withdrawn.
production_access.withdrawn production_access The organization withdrew its open access request.
production_activation.submitted production_activation The organization sent its activation request with the SUNAT screenshots.
production_activation.changes_requested production_activation The staff asked for changes to the activation request; the note says what.
production_activation.resubmitted production_activation The organization sent the activation request again after the requested changes.
production_activation.approved production_activation The staff approved the activation request: the enrolment of the RUC with the provider is in progress.
production_activation.rejected production_activation The staff rejected the activation request, with its reason.
production_activation.withdrawn production_activation The activation request was withdrawn.
production_activation.activated production_activation Production was activated on this request: the organization issues for real.
establishment.created establishment An establishment of the issuer was registered, with its SUNAT annex code.
establishment.updated establishment An establishment changed its name, address or status. Invoices already issued keep their copy.
brand.updated brand The brand of the organization changed. Templates that read it use the new values from the next document; issued documents keep theirs.
asset.uploaded asset An image was uploaded to the library of the organization, or replaced under the same name.
asset.removed asset An image was removed from the library. Published template versions keep the bytes they pinned.
template.created template A template of the printed invoice was created.
template.draft_saved template The draft of a template was saved.
template.published template A new version of the template was published. Test documents use it at once; production keeps its own until it is promoted.
template.promoted template A version of the template was promoted: production documents use it from now on.
template.archived template The template was archived. Documents already issued keep their version.
invoice.pdf_ready invoice The PDF of the invoice is ready to download.
invoice.render_ready invoice A requested render of the invoice (another template or format) is ready.
file_share_link.created file_share_link A share link to a file of an invoice was created.
file_share_link.revoked file_share_link A share link to a file of an invoice was revoked.
issuer.ruc_verified issuer The RUC of the issuer was verified against SUNAT data.
issuer.ruc_not_found issuer The RUC of the issuer does not exist at SUNAT: the organization cannot ask for production.
issuer.activated issuer The issuer was activated for production: its RUC is locked to it and it can issue for real.
provider_connection.created provider_connection A connection to a provider was added to the issuer.
provider_connection.updated provider_connection The configuration or the state of a provider connection changed.
provider.account_blocked provider The provider refuses every operation of the account. Invoices stay in process and go out when it recovers.
provider.account_recovered provider The provider account works again; what was waiting is being sent.
invoice.void_requested invoice A void of the invoice was requested. The invoice is still accepted.
invoice.voided invoice SUNAT accepted the void. The invoice is voided.
invoice.void_rejected invoice SUNAT rejected the void. The invoice is still accepted. yes
invoice.void_held invoice The provider gave an answer about the void that the service cannot interpret. The void is held: nothing is resent, and the staff of the service was told.
invoice.void_released invoice The staff of the service released a held void: it first asks the provider, then goes on.
invoice.void_failed invoice The void could not be completed (for example, its window expired). The invoice is still accepted. yes
invoice.void_stalled invoice The void of the invoice has been in process longer than expected. The invoice is still accepted; nothing is lost, and someone should look. yes
invoice.reopened invoice A failed or rejected invoice was corrected and is in process again. Its previous attempt is kept in its history.
invoice.externally_reversed invoice A person recorded that the invoice was reversed by hand at the provider. A note, not a fiscal state.
invoice.files_stored invoice The files of the invoice (XML, CDR, PDF) are stored and can be downloaded.
invoice.file_failed invoice A file of the invoice could not be stored or rendered. It can be asked again.
invoice.email_sent invoice An email about the invoice was sent.
invoice.email_not_sent invoice An email about the invoice was deliberately not sent; the event says why. Its content stays readable.
invoice.email_failed invoice An email about the invoice could not be sent after retrying.
invoice.email_held invoice An email to the customer is held because the PDF it carries could not be rendered. It is never sent without it, and goes out by itself once the PDF is rendered again and stored. yes
webhook_endpoint.created webhook_endpoint A webhook destination was created. The secret is never in the event.
webhook_endpoint.updated webhook_endpoint The URL, the subscribed types or the state of a webhook destination changed.
webhook_endpoint.deleted webhook_endpoint A webhook destination was deleted. Carries the destination as it was, without its secret.
webhook_endpoint.disabled webhook_endpoint The service disabled a webhook destination that kept failing. Nothing is delivered to it until it is enabled again. yes
webhook_endpoint.secret_rotated webhook_endpoint The signing secret of a webhook destination was rotated. The previous one still signs until it expires.
invitation.created invitation A person was invited to the organization. The token is never in the event.
invitation.resent invitation An invitation was sent again with a new token; the previous token stopped working. The token is never in the event.
invitation.accepted invitation An invitation was accepted; the person is now a member.
invitation.revoked invitation An invitation was revoked. Carries the invitation as it was, without its token.

Alerts are grouped: one email per organization for everything that happened in 15 minutes, naming the first 5 cases. A simulated event never raises one.

Type to search…

↑↓ navigate↵ selectEsc close