Webhooks API Reference

Webhooks allow you to be notified about state changes in a given purchase.

Links - Webhooks usage guide


Overview

Webhooks in Ramp Instant are very simple. If you pass a proper webhook URL during widget initialization, we will call this URL for every major status change of the purchase initialized in that widget instance. Each call to your URL will contain details about the purchase and its state change history.

Headers

X-Body-Signature

For your safety we sign our webhook calls. The messages are signed using an ECDSA key and a sha256 digest.

To create a message to sign, we serialize the original request body (JSON) with fast-json-stable-stringify module, which sorts the object keys before serialization, creating a deterministic output.

Then, we sign the message using an ECDSA key (based on secp256k1 curve) with a sha256 digest function.

The signature is finally encoded to base64 and sent with the original request in the X-Body-Signature header.

Use our public key to verify incoming POST calls (for example using nodejs crypto.verify function).

Our public key

-----BEGIN PUBLIC KEY-----
MFYwEAYHKoZIzj0CAQYFK4EEAAoDQgAElvxpYOhgdAmI+7oL4mABRAfM5CwLkCbZ
m64ERVKAisSulWFC3oRZom/PeyE2iXPX1ekp9UD1r+51c9TiuIHU4w==
-----END PUBLIC KEY-----

See our integration guide for more tips and an example verifier apps in JS and Python.

Available webhooks

webhookStatusUrl

This webhook is called for every major state update of the purchase. It will be executed using HTTP POST and will contain JSON data with a Purchase object inside:

interface PurchaseStatusWebhookEvent {
  type: 'CREATED' | 'RELEASED' | 'RETURNED' | 'ERROR';
  purchase: RampInstantPurchase;
}

The RampInstantPurchase object is the same as in the SDK purchase status events.

Example event

HTTP POST

Headers:

  • Content-Type: application/json

  • X-Body-Signature: MEYCIQDNKwVgcFj76+JiazvnzrYgf8K5GUNJ+NUVeoR0buVMxAIhAJzuV8wa5M/oyNXlwWUgIG4HEEZy4SYEqJLkf+sThunQ

Body:

{
  "type": "CREATED",
  "purchase": {
    "id": "311",
    "endTime": null,
    "tokenAddress": null,
    "asset": {
      "address": null,
      "symbol": "ETH",
      "name": "Ether",
      "decimals": 18
    },
    "escrowAddress": null,
    "cryptoAmount": "30000000000000000",
    "ethAmount": "30000000000000000",
    "tokenAmount": null,
    "fiatCurrency": "GBP",
    "fiatValue": 0.04,
    "assetExchangeRate": 1.27378941587846,
    "poolFee": 0.000573205237145307,
    "rampFee": 0.000573205237145307,
    "purchaseHash": "...",
    "purchaseViewToken": "...",
    "receiverAddress": "0x2222222222222222222222222222222222222222",
    "actions": [
      {
        "id": 1176,
        "newStatus": "INITIALIZED",
        "timestamp": "2019-10-24T14:41:39.372Z"
      },
      {
        "id": 1177,
        "newStatus": "ESCROW_CREATING",
        "timestamp": "2019-10-24T14:41:41.065Z",
        "details": "0x0ea7394fc7430be5c17484cdda08b138b1bb9f6f1af9f827a7b6df50ca0cfa25"
      }
    ]
  }
}