Webhooks

Back to Wiki Home

You can edit webhooks on your resource by going to your resource page and clicking the "Webhooks" button in the edit section.

Automatic Discord Integration
Polymart automatically integrates with Discord webhooks. However, this doesn't give you nearly as much customization as if you build your own API for receiving webhooks. If you want to learn more about how to build your own API for receiving webhooks, keep reading!

Webhook Overview
ping — Sent whenever you click the "ping" button on your resource's webhooks page
resourceUpdate — Sent whenever you post an update to your resource

About Webhooks
When a webhook event is called, Polymart will send a request to the URL you provide on your resource page. With each request, the following headers will be sent:

X-Polymart-Webhook-Version: 1

X-Polymart-Signature will be a signature that verifies that the webhook request is in-fact valid. This is a SHA256 HMAC hash, where the data is the data that was POSTed, and the key is your webhook secret. Your webhook secret generated when you create a new webhook. YOU MUST VALIDATE THAT THIS IS CORRECT. If you do not, attackers will easily be able to send random, invalid webhooks to your server

The data that is POSTed to your webhook will be in this format

{
  "event": <event type>,
  "time": <current unix time>,
  "nonce": <random nonce>,
  "payload": {
    <key 1>: <val 1>,
    <key 2>: <val 2>,
    <...>: <...>
  }
}

So, the top-level information might look something like this

{
  "event": "resourceUpdate",
  "time": 1600828225,
  "nonce": "k_4d7MaGp9TjkMqs",
  "payload": <...>
}

Putting it all together, this is what a full valid request to https://example.com/polymartWebhook might look like, given the webhook secret cLkCtkhranczMdPR

POST /polymartWebhook HTTP/1.1
X-Polymart-Webhook-Version: 1
X-Polymart-Signature: 802284a2c03838982967ac84753ac927caf7f4208268fdd62b81d3fd4fe0b7e7
Content-Type: application/json
Content-Length: 166
{
    "event": "testEvent",
    "time": 1600828225,
    "nonce": "_GaZHrkwRHJ2x6R5",
    "payload": {
        "webhook": "https://example.com/polymartWebhook"
    }
}

ping Back to top

Use this to test your webhook! This webhook event is called when you click the "send a ping" button on your resource's webhooks page.

Format

{
  "event": "ping",
  "time": <current unix time>,
  "nonce": <random nonce>,
  "payload": {
    "resource": {
      "id": <resource id>,
      "title": <resource title>,
      "subtitle": <resource subtitle>,
      "url": <resource url>
    },
    "webhook": {
      "url": <your webhook url>
    }
  }
}

Example

{
  "event": "ping",
  "time": 1600828225,
  "nonce": "Pt9h4stJX6IK_xNq",
  "payload": {
    "resource": {
      "id": "1",
      "title": "CustomItems",
      "subtitle": "Design new Custom items and blocks!",
      "url": "https://polymart.org/resource/1"
    },
    "webhook": {
      "url": "https://example.com/polymartWebhook"
    }
  }
}

If your webhook secret is cLkCtkhranczMdPR, then the signature of this request will be ec3295401119801ec9137346857743d10dd4fbe5b670f937f9d78c8aa081d16d

resourceUpdate Back to top

This webhook event is called when your resource is updated.

Format

{
  "event": "resourceUpdate",
  "time": <current unix time>,
  "nonce": <random nonce>,
  "payload": {
    "resource": {
      "id": <resource id>,
      "title": <resource title>,
      "subtitle": <resource subtitle>,
      "url": <resource url>
    },
    "previous": {
      "version": <old version>,
      "id": <old version ID>,
      "time": <old version update time>,
      "size": <old size>,
      "fileType": <old file type>,
      "branch": <beta|snapshot|release>
    },
    "update": {
      "version": <new version>,
      "id": <new version ID>,
      "time": <update time>,
      "size": <new size>,
      "fileType": <new file type>,
      "branch": <beta|snapshot|release>,
      "title": <update title>,
      "description": <update description>
    }
  }
}

Example

{
  "event": "resourceUpdate",
  "time": 1600828225,
  "nonce": "BElS_vOZOkFyWg1d",
  "payload": {
    "resource": {
      "id": "1",
      "title": "CustomItems",
      "subtitle": "Design new Custom items and blocks!",
      "url": "https://polymart.org/resource/1"
    },
    "previous": {
      "version": "2.19.5",
      "id": "91",
      "time": 1600824625,
      "size": "716624",
      "fileType": "jar",
      "branch": "snapshot"
    },
    "update": {
      "version": "3.0",
      "id": "107",
      "time": 1600828225,
      "size": "718232",
      "fileType": "jar",
      "branch": "release",
      "title": "Automatic Resource Pack Generation",
      "description": "This version adds an automatic resource pack generator to CustomItems!"
    }
  }
}

If your webhook secret is cLkCtkhranczMdPR, then the signature of this request will be f5455a6f2c3e6a141876585b2d1e630d0b8d7cec7376cf1272ebe0f1a89d1198