Webhooks

We'll POST JSON to your URL whenever a new bot is published.

Remove a webhook

Use the URL you saved.

What we POST

Every delivery is a JSON body with an event type. We send a ping when you add the URL. After that, each new bot is bot.created. Respond with 2xx. After 10 failures in a row we stop calling you.

Headers

Field	Meaning
`Content-Type`	`application/json`
`User-Agent`	`GrokBots.best-Webhook/1.0`
`X-GrokBots-Event`	`ping` or `bot.created`.
`X-GrokBots-Delivery`	A unique id for this attempt.

ping

{
  "id": "evt_…",
  "type": "ping",
  "created_at": "2026-04-01T00:00:00.000Z",
  "data": {}
}

bot.created

data is the same object as GET /api/bots.

{
  "id": "evt_…",
  "type": "bot.created",
  "created_at": "2026-04-01T00:00:00.000Z",
  "data": {
    "id": "…",
    "slug": "example-bot",
    "name": "Example Bot",
    "description": "…",
    "author": "@handle",
    "url": "https://grokbots.best/bots/example-bot",
    "source_url": "https://x.com/handle/status/123",
    "integrations": ["github"],
    "categories": ["Engineering"],
    "created_at": "2026-04-01T00:00:00.000Z"
  }
}

Add a webhook

POST an HTTPS URL. We ping it and only keep a 2xx response. We don't list saved URLs, so keep a copy to remove it later.

POSThttps://grokbots.best/api/webhooks/bots

Request

Field	Meaning	Required
`url`	An HTTPS endpoint, like `https://example.com/hooks/grokbots`.	yes

POST https://grokbots.best/api/webhooks/bots
Content-Type: application/json

{
  "url": "https://example.com/hooks/grokbots"
}

Response

Field	Meaning
`id`	Saved webhook id.
`url`	The canonical HTTPS URL we will POST to.

{
  "id": "…",
  "url": "https://example.com/hooks/grokbots"
}

Status 200 with id and url. 409 if that URL is already registered. 400 for an invalid URL, a private or local address, or a ping that is not 2xx.

Remove a webhook

DELETE the same URL you registered. Anyone with that URL can remove it.

DELETEhttps://grokbots.best/api/webhooks/bots

Request

Field	Meaning	Required
`url`	The HTTPS endpoint to stop notifying.	yes

DELETE https://grokbots.best/api/webhooks/bots
Content-Type: application/json

{
  "url": "https://example.com/hooks/grokbots"
}

Response

Field	Meaning
`url`	The URL we removed.

{
  "url": "https://example.com/hooks/grokbots"
}

Status 200 with url. 404 if nothing is registered at that URL. 400 for an invalid URL.