Skip to main content
PATCH
Update your webhook URLs
Points the webhooks on your API key somewhere new, without going through the dashboard. Whichever key you send in x-api-key is the key that changes — there is no id in the path, so a key can only ever reconfigure itself.

The two webhooks

  • rampWebhookURL — onramp and offramp order updates, posted at every status transition. It is the default for every order opened with this key: an order that sets its own webhookURL is announced there instead, and one that leaves it out is announced here.
  • paymentWebhookURL — payment settlements.
Send either, or both. A field you leave out is left exactly as it was, so moving one webhook never disturbs the other. The response is the full configuration after the change, both fields included, so you can confirm what the key now holds without a second call.

Your signing secret

The response also carries webhookSecret — the secret every delivery to these URLs is signed with, so your handler can tell a real delivery from anything else that finds the URL. It is the same secret each time; changing a URL does not change it. Verifying is a few lines, and Webhook signatures covers it in full. If you are moving a webhook to a new endpoint, that is the moment to add verification to it.

Turning a webhook off

Send the field as an empty string:
The URL is removed and those deliveries stop; the key keeps working for everything else. This is the only way to clear one — omitting the field means “leave it alone”, not “remove it”. Anything else has to be a valid absolute URL, or the request is a 400 and nothing changes. A body naming neither field is also a 400 rather than a silent no-op, since it usually means a misspelled field name.

After changing it

A new paymentWebhookURL takes effect immediately, including for payments already in flight — a payment opened a minute ago will settle to whatever paymentWebhookURL says at the moment it settles, not what it said when it was created. rampWebhookURL works differently. An order that did not name its own webhook takes the key’s rampWebhookURL when it is created, and keeps it. Changing the URL covers every order you open from then on; orders already open keep reporting to the URL they started with. Worth pairing with Test your webhook: change the URL, then fire a sample payload at it and confirm your new endpoint answers 2xx before you rely on it. One thing to check when moving a URL: redirects are not followed, so a delivery to a URL that redirects — http to https, or a bare domain to www — counts as failed. Point the webhook at the final destination.

Authorizations

x-api-key
string
header
required

Body

application/json
rampWebhookURL
string

Where onramp and offramp order updates are posted. Send an empty string to stop receiving them.

Example:

"https://example.com/webhook"

paymentWebhookURL
string

Where settled payments are posted. Send an empty string to stop receiving them.

Example:

"https://example.com/payment-webhook"

Response

The webhook configuration now on the key

rampWebhookURL
string

Where onramp and offramp order updates are posted.

Example:

"https://example.com/webhook"

paymentWebhookURL
string

Where settled payments are posted.

Example:

"https://example.com/payment-webhook"

webhookSecret
string

The secret every delivery to these URLs is signed with. Verify a delivery by computing HMAC-SHA256 over {X-PAJ-Timestamp}.{raw body} with this secret and comparing it, in constant time, against the hex digest in X-PAJ-Signature (after the v1= prefix). Reject deliveries whose timestamp is more than a few minutes old.

Example:

"whsec_2f1c…"