Skip to content

Webhook Ping

Sent to verify an endpoint: once when a webhook URL is saved from the Beyond dashboard, and whenever a test ping is requested there. It carries no domain change. Answer any 2xx and discard the body.
Event type webhook.ping
Resource type webhook-ping-events
Triggered by Saving a webhook URL or sending a test ping from the dashboard (personal users)

When It Fires

A personal user configures their webhook from the Beyond dashboard. Beyond persists a new URL only after a signed ping to it returns a 2xx, and the dashboard's "Send test ping" action sends the same ping on demand. The ping is signed with the user's signing secret like every other delivery, so a receiver that enforces signatures from day one passes verification.

sequenceDiagram
    participant U as Dashboard
    participant BP as Beyond Pricing
    participant P as Your Endpoint

    U->>BP: Save URL
    BP->>P: POST signed webhook.ping (no redirects, timeout)
    alt Any 2xx
        P-->>BP: 200 OK
        BP-->>U: URL saved, verified
    else 3xx / other status / timeout / network error
        P-->>BP: error
        BP-->>U: URL not saved, reason shown
    end

A ping is not gated on your event selection: it is sent even when webhook.ping is not in your subscribed events, because its purpose is to confirm the endpoint before any real event is delivered. It is sent once and never retried; a failed ping changes nothing on Beyond's side.

Payload

{
  "meta": {
    "type": "webhook.ping",
    "sent-at": "2026-08-20T12:34:56Z"
  },
  "data": {
    "type": "webhook-ping-events",
    "id": "msg_01K2Z6M0K3QK7YV8N2C4B5A6D7",
    "attributes": {
      "message": "Beyond webhook endpoint verification"
    },
    "relationships": {
      "user": {
        "data": { "type": "users", "id": "456" },
        "links": { "related": "https://developers.beyondpricing.com/api/v1/users/456/" }
      }
    }
  }
}

The meta envelope is documented in the Payload Envelope section.

data.attributes

Field Type Description
message string Human-readable reason for the ping. Informational only.

data.relationships

Relationship Description
user The Beyond user whose webhook is being verified ({ "type": "users", "id": … }).

Handling Tips

  • Verify the signature, then return 200 (or any 2xx) without doing any work. A slow handler can hit the timeout and the URL is not saved.
  • Do not follow the event with a lookup: the ping describes no change.
  • Route on meta.type and treat webhook.ping like any other unknown type: acknowledge and ignore.