Create a webhook subscription
Register an HTTPS endpoint to receive webhook events for deposit-address transfers. Requires an API key with the deposit-address permission (Bearer auth). A subscription is persistent: it receives every matching event — across all of your deposit addresses — until you delete it. A 2xx response to a delivery only acknowledges that one event; it does not end the subscription. The signing secret is returned once in this response and never again — store it to verify delivery signatures.
Authorization
bearerAuth API key for authentication.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
Callbacks
event
curl -X POST "https://across.to/api/v1/webhooks/subscriptions" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com/webhooks/across", "filter": { "eventTypes": [ "pda_transfer.deposit-pending" ] } }'{
"id": "whsub_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
"secret": "whsec_kZ3vN8pXqLmR2sT5wY7bC1dF4gH6jK9n",
"secretHash": "9f2c3b7a1e4d5f6089ab2c3d4e5f60718293a4b5c6d7e8f9012345678abcdef0"
}{
"error": "ValidationError",
"message": "At path: filter -- Expected an object, but received: undefined"
}{
"error": "UnauthorizedError",
"message": "A valid Authorization: Bearer <apiKey> header is required."
}{
"error": "ForbiddenError",
"message": "API key lacks the 'deposit-address' permission."
}{
"error": "ConflictError",
"message": "A subscription with this url already exists for this integrator."
}{
"error": "ValidationError",
"message": "Invalid request body"
}Get a transfer GET
Returns the current state of one transfer; `orderId` is the same value as the `quoteId` from `POST /v1/quotes`, so no lookup is needed. Gate anything irreversible on `status.finalized`.
List webhook subscriptions GET
List the webhook subscriptions owned by the caller's API key, oldest first. The raw signing secret is never included — only its `secretHash`.