Skip to main content

Upgrade to the signed format

Webhooks in the previous format keep working unchanged. When you want signatures, automatic retries, and the dispute, refund, and payout events, create a replacement from the Dashboard. Your current webhook keeps receiving events until you activate the replacement, and you can switch back for 72 hours.

What changes​

Previous formatSigned format
AuthenticationThe X-Webhook-Secret header carries the secret.The X-Onvo-Signature header carries a timestamped signature; the secret is never sent. See Verify signatures.
Body{ "type", "data" } with the full object.An envelope with id, type, and data.object, which holds only the public fields.
Event namesWith hyphens: payment-intent.succeeded.With underscores: payment_intent.succeeded.
RetriesA single attempt, with no retries.Automatic retries: up to 72 hours in live mode.
EventsPayments, renewals, subscription schedules, Checkout, and transfers.Also disputes, refunds, and payouts.
SelectionReceives every event.Receives only the events you select.

Name equivalents:

Previous formatSigned format
payment-intent.succeededpayment_intent.succeeded
payment-intent.failedpayment_intent.failed
payment-intent.deferredpayment_intent.processing
subscription.renewal.succeededsubscription_renewal.succeeded
subscription.renewal.failedsubscription_renewal.failed
subscription-schedule.createdsubscription_schedule.created
subscription-schedule.updatedsubscription_schedule.updated
subscription-schedule.activatedsubscription_schedule.activated
subscription-schedule.canceledsubscription_schedule.canceled
subscription-schedule.releasedsubscription_schedule.released
subscription-schedule.completedsubscription_schedule.completed
subscription-schedule.phase-transitionedsubscription_schedule.phase_transitioned
subscription-schedule.transition-failedsubscription_schedule.transition_failed
checkout-session.succeededcheckout_session.succeeded
mobile-transfer.receivedmobile_transfer.received

The objects change too. For example, a payment intent carries customerId and latestCharge instead of the full customer and the list of charges. If you need more data, fetch it from the API with the object's ID.

Steps​

  1. In Developers > Webhooks, find your webhook under Existing integrations and choose Upgrade available.
  2. Review the replacement's name, URL, and events. The Dashboard shows how many events your webhook received in recent days and warns you if any of them has no equivalent in the signed format.
  3. Choose Create disabled replacement and save the new signing secret (whsec_...). Your current webhook stays active.
  4. Update your server so it verifies the signature and reads the new envelope and event names. During the upgrade, you can tell the formats apart by header: signed requests carry X-Onvo-Signature and previous-format requests carry X-Webhook-Secret.
  5. Choose Test connection. A successful test is valid for 24 hours. It is invalidated if you change the URL, rotate the signing secret, or a later test fails.
  6. Check I verified the new signature in my receiver and choose Activate replacement. ONVO activates the replacement and disables the previous webhook at the same time.

Each event is sent in the format that was active when it happened, never in both: an event that happened just before activation can still arrive in the previous format after the switch. The exception is mobile_transfer.received, which can arrive in both formats if the transfer is received right during activation. The two formats do not share the event ID, so discard duplicates using the object's ID. ONVO does not resend, in the new format, events already delivered in the previous one.

Switch back to the previous webhook​

For 72 hours after activation, you can choose Restore previous endpoint: the previous webhook receives new events again and the replacement goes back to being a draft. To use it again, it needs a successful connection test from the last 24 hours, the confirmation that you verified the signature, and Activate replacement. Events that happened while the other format was active are not resent.

If you have not activated the replacement yet, you can Discard draft without affecting your current webhook.

Delete or reactivate the previous webhook​

ONVO keeps your server from receiving each event in both formats:

  • You cannot reactivate the previous webhook while its replacement is active. To switch back, use Restore previous endpoint within the 72 hours, or deactivate the replacement first.
  • You cannot restore the previous webhook while another active endpoint uses its URL. Deactivate that endpoint first.
  • You cannot reactivate a previous-format webhook, or change the URL of an active one, while an active signed endpoint uses that URL.
  • You cannot activate an endpoint while the webhook it replaced is active, or while another active previous-format webhook uses its URL. Deactivate that webhook first.
  • You cannot create or edit an endpoint to use the URL of an active previous-format webhook: choose Upgrade available on that webhook.

If you delete the previous webhook, ONVO discards its upgrade draft and revokes the draft's secret. If the replacement is already active, it keeps working, but you can no longer restore the previous webhook. The previous webhook's logs are deleted too.