Skip to main content

Webhooks

Webhooks are automated messages sent from Phosphor in response to specific events. These messages are sent to a URL you specify and carry information pertinent to the event that triggered them. This mechanism essentially enables automatic communication between Phosphor and your application or URL.

Benefits of Using Webhooks​

  • Real-time Processing: Webhooks can provide real-time information to your applications, which is particularly useful for events that require immediate action.
  • Efficiency: They eliminate the need for constant polling our API services, reducing resource consumption.
  • Customization: Webhooks receive specific event related payloads, ensuring that your receiving application gets exactly the information it needs.

Managing Webhooks​

You can manage Webhook from the Developer Dashboard by navigating to Settings > Webhooks.

  • Creating a webhook requires the following info: name, url, secret.
  • Disable/enable sending events.
  • Send test event to your URL.

Types of Webhook Events​

Phosphor supports two main types of webhooks:

  • ITEM events: such as, minting, transferring, and burning.
  • LISTING events: such as, creation, cancellation, and completion.

Receiving Webhook Events​

After creating a webhook, events (above) will trigger a POST request containing relevant information to the URL you provided. Each POST request will include the secret you supplied, allowing you to confirm within your app that the request was indeed sent by us. If you receive a request that either lacks the secret or contains a secret that doesn't match the one you provided, you should reject that request!

Phosphor Webhook Requests​

  • Method: POST
  • User-Agent: "phosphor-webhook-bot/0.0.1"
  • Phosphor-Webhook-Secret: "your-secret-key"

Example Payloads​

TOKEN_TX Example
{
  "id": "998e6642-2333-4fa7-9abb-2fbf5bfda797",
  "type": "TOKEN_TX",
  "data": {
    "item": {
      "listing": null,
      "id": "cb23cb8d-e415-42c4-beef-3f068aee05dd",
      "token_id": "111",
      "media": {
        "image": null
      },
      "attributes": {
        "title": "A test token",
        "description": "This is not a real token, for testing only"
      },
      "collection_id": "d213af97-0014-40c7-8d45-cccccf2d09c8",
      "token_contract": {
        "tx_hash": null,
        "capabilities": ["ERC721"],
        "address": "0xde6afDD5bD30745542cDfabD001916A365Dc4c42",
        "symbol": "FAKE",
        "deploy_tx_id": "a03b9fb7-ce53-48c0-9a6f-ff3af57e13ee",
        "token_type": "ERC721",
        "network_id": 1
      }
    },
    "tx_hash": "0x72641cefc85e187e998be6e8e2752104808d74273f000d992b77457e7b8e3f15",
    "to_addr": "0x75A181dc9A3E1b746D62E0be6819f7Bdf1110895",
    "log_index": 2,
    "tx_id": "181b0914-6081-46cd-911b-22ed96af8379",
    "token_id": "111",
    "from_addr": "0xfc186E95c40e5F96C05F811fE821d9433c9394F4",
    "contract_address": "0xde6afDD5bD30745542cDfabD001916A365Dc4c42",
    "quantity": "1",
    "block_timestamp": "2024-06-07T18:08:15+00:00",
    "tx_type": "TRANSFER",
    "block_number": "12345"
  }
}
LISTING Example
{
  "type": "CREATED",
  "listing": {
    "id": "9698da0b-a153-4d56-9bee-f761a3a84585",
    "price": "0",
    "policy": {
      "type": "FCFS",
      "tx_payer": "BUYER",
      "max_per_user": 100,
      "email_claim_duration": null,
      "item_assignment_strategy": "AUTOMATIC",
      "payment_session_duration": null
    },
    "status": "ACTIVE",
    "item_id": "7b5451bc-ad18-435c-a454-c7357f73707f",
    "currency": "ETH",
    "end_time": "2023-12-15T15:06:43.650000+00:00",
    "sale_type": "DEFAULT",
    "start_time": "2023-12-08T15:06:44.712862+00:00",
    "campaign_id": null,
    "collection_id": null,
    "quantity_listed": 2147483647,
    "payment_providers": ["MINT_VOUCHER"],
    "quantity_remaining": 2147483647,
    "max_quantity_per_tx": 1,
    "settlement_currency": {
      "MINT_VOUCHER": "ETH"
    }
  }
}

Sending Test Event​

To assist in developing your application, you may find it useful to receive sample requests from Phosphor to your application or URL. By utilizing our webhook test service, you can initiate a sample on-demand event for testing purposes.

Example payload your URL will receive
{
  "id": "998e6642-2333-4fa7-9abb-2fbf5bfda797",
  "type": "TOKEN_TX",
  "data": {
    "item": {
      "listing": null,
      "id": "cb23cb8d-e415-42c4-beef-3f068aee05dd",
      "token_id": "111",
      "media": {
        "image": null
      },
      "attributes": {
        "title": "A test token",
        "description": "This is not a real token, for testing only"
      },
      "collection_id": "d213af97-0014-40c7-8d45-cccccf2d09c8",
      "token_contract": {
        "tx_hash": null,
        "capabilities": ["ERC721"],
        "address": "0xde6afDD5bD30745542cDfabD001916A365Dc4c42",
        "symbol": "FAKE",
        "deploy_tx_id": "a03b9fb7-ce53-48c0-9a6f-ff3af57e13ee",
        "token_type": "ERC721",
        "network_id": 1
      }
    },
    "tx_hash": "0x72641cefc85e187e998be6e8e2752104808d74273f000d992b77457e7b8e3f15",
    "to_addr": "0x75A181dc9A3E1b746D62E0be6819f7Bdf1110895",
    "log_index": 2,
    "tx_id": "181b0914-6081-46cd-911b-22ed96af8379",
    "token_id": "111",
    "from_addr": "0xfc186E95c40e5F96C05F811fE821d9433c9394F4",
    "contract_address": "0xde6afDD5bD30745542cDfabD001916A365Dc4c42",
    "quantity": "1",
    "block_timestamp": "2024-06-07T18:08:15+00:00",
    "tx_type": "TRANSFER",
    "block_number": "12345"
  }
}
"Unsupported Events"
  • No event is sent when a listing is updated.
  • Collection-level actions, like deploying a new collection or updating its metadata, do not trigger webhook events.
info

If you're interested in an event that we currently do not support, please reach out to us with your request.

Last updated on