{"openapi":"3.0.3","info":{"title":"Cito API webhooks","version":"1.0.0","description":"Create and manage webhooks with your API key. A key only reaches webhooks on its own account. GET /webhooks/events lists every event with real examples.","contact":{"email":"support@citoapi.com"}},"servers":[{"url":"https://api.citoapi.com/api/v1"}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"x-api-key"},"BearerKey":{"type":"http","scheme":"bearer"}},"schemas":{"Error":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string"},"code":{"type":"string","example":"WEBHOOK_PLAN_REQUIRED"},"fix":{"type":"string"},"docs":{"type":"string"},"upgradeUrl":{"type":"string"},"currentPlan":{"type":"string"},"requiredPlan":{"type":"string"}}},"Webhook":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"filters":{"type":"object","nullable":true},"isActive":{"type":"boolean"},"failureCount":{"type":"integer"},"lastTriggered":{"type":"string","format":"date-time","nullable":true},"lastSuccess":{"type":"string","format":"date-time","nullable":true},"lastFailure":{"type":"string","format":"date-time","nullable":true},"lastError":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"nextRetryAt":{"type":"string","format":"date-time","nullable":true},"deliveryPaused":{"type":"boolean"}}},"WebhookInput":{"type":"object","required":["url","events"],"properties":{"url":{"type":"string","example":"https://your-domain.com/webhooks/cito","description":"Public URL. Private, local and metadata addresses are refused, on create and on every send."},"events":{"type":"array","items":{"type":"string"},"example":["cs2.match.completed"]},"filters":{"type":"object","example":{"league":"LEC"}}}},"Delivery":{"type":"object","properties":{"deliveryId":{"type":"string"},"eventId":{"type":"string"},"eventType":{"type":"string"},"matchId":{"type":"string","nullable":true},"seq":{"type":"integer","nullable":true},"status":{"type":"string","enum":["delivered","failed","skipped_backoff"]},"httpCode":{"type":"integer","nullable":true},"error":{"type":"string","nullable":true},"attempt":{"type":"integer"},"replayed":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"eventCreatedAt":{"type":"string","format":"date-time"},"diagnosis":{"type":"string"}}},"Inbox":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"url":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"expired":{"type":"boolean"},"requestCount":{"type":"integer"},"latestRequestId":{"type":"string","nullable":true}}}}},"paths":{"/webhooks/events":{"get":{"summary":"Every webhook event, for every game","description":"Public. Each event has a description, when it fires, its status (active, quiet, not_observed), measured frequency, minimum plan, filters, field names and a real example.","security":[],"parameters":[{"name":"game","in":"query","schema":{"type":"string"}},{"name":"event","in":"query","schema":{"type":"string"}},{"name":"examples","in":"query","schema":{"type":"boolean","default":true}},{"name":"fields","in":"query","schema":{"type":"boolean","default":true}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/webhooks":{"get":{"summary":"List your webhooks","security":[{"ApiKey":[]},{"BearerKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"webhooks":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}},"availableEvents":{"type":"array","items":{"type":"string"}}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan does not include this. See `upgradeUrl`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a webhook","description":"Pro or Scale. The secret is returned once. The account owner is emailed when a webhook is created with an API key.","security":[{"ApiKey":[]},{"BearerKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookInput"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"webhook":{"allOf":[{"$ref":"#/components/schemas/Webhook"},{"type":"object","properties":{"secret":{"type":"string"}}}]},"warnings":{"type":"array","items":{"type":"string"}}}}}}},"400":{"description":"Bad request: `error` says what is wrong, `fix` what to do","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan does not include this. See `upgradeUrl`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests. See Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/{id}":{"get":{"summary":"One webhook (never the secret)","security":[{"ApiKey":[]},{"BearerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"webhook":{"$ref":"#/components/schemas/Webhook"}}}}}},"404":{"description":"Not found on your account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Change URL, events, filters or isActive","description":"Changing the URL with an API key emails the account owner.","security":[{"ApiKey":[]},{"BearerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"filters":{"type":"object","nullable":true},"isActive":{"type":"boolean"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"webhook":{"$ref":"#/components/schemas/Webhook"},"warnings":{"type":"array","items":{"type":"string"}}}}}}},"400":{"description":"Bad request: `error` says what is wrong, `fix` what to do","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan does not include this. See `upgradeUrl`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found on your account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete a webhook","security":[{"ApiKey":[]},{"BearerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}},"404":{"description":"Not found on your account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/{id}/test":{"post":{"summary":"Send a test delivery and get a diagnosis","description":"No body: a short test ping. {\"event\":\"cs2.match.completed\"}: a real recent sample of that event, signed, marked test: true, data.test: true and X-Cito-Test: true.","security":[{"ApiKey":[]},{"BearerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status":{"type":"string","enum":["delivered","failed"]},"statusCode":{"type":"integer","nullable":true},"latencyMs":{"type":"integer"},"diagnosis":{"type":"string"},"sample":{"type":"object"},"testEventId":{"type":"string"}}}}}},"400":{"description":"Bad request: `error` says what is wrong, `fix` what to do","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan does not include this. See `upgradeUrl`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found on your account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests. See Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/{id}/regenerate-secret":{"post":{"summary":"Replace the signing secret (returned once)","security":[{"ApiKey":[]},{"BearerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"secret":{"type":"string"}}}}}},"404":{"description":"Not found on your account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/{id}/reset":{"post":{"summary":"Clear failures and turn the webhook back on","security":[{"ApiKey":[]},{"BearerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Not found on your account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/reset":{"post":{"summary":"Clear failures on all your webhooks","security":[{"ApiKey":[]},{"BearerKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"403":{"description":"Plan does not include this. See `upgradeUrl`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/{id}/deliveries":{"get":{"summary":"Delivery log, newest first","security":[{"ApiKey":[]},{"BearerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":100}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"nextCursor from the previous page"},{"name":"status","in":"query","schema":{"type":"string"},"description":"delivered, failed, skipped_backoff; comma separated"},{"name":"event","in":"query","schema":{"type":"string"}},{"name":"matchId","in":"query","schema":{"type":"string"}},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"until","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"include","in":"query","schema":{"type":"string","enum":["summary"]},"description":"summary adds 7-day counts by status"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Delivery"}},"nextCursor":{"type":"string","nullable":true},"filters":{"type":"object"},"summary":{"type":"object"}}}}}},"404":{"description":"Not found on your account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/{id}/deliveries/{deliveryId}":{"get":{"summary":"One delivery with its payload","security":[{"ApiKey":[]},{"BearerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"deliveryId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"delivery":{"allOf":[{"$ref":"#/components/schemas/Delivery"},{"type":"object","properties":{"payload":{"type":"object"}}}]}}}}}},"404":{"description":"Not found on your account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/{id}/replay":{"post":{"summary":"Re-send a stored event or a match","description":"Sends to your own webhook only, marked data.replayed true and data.original_event_id. At most 10 events per call.","security":[{"ApiKey":[]},{"BearerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"eventId":{"type":"string"},"matchId":{"type":"string"},"eventType":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request: `error` says what is wrong, `fix` what to do","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan does not include this. See `upgradeUrl`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found on your account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/{id}/catch-up":{"post":{"summary":"Re-send the match and result events you missed","description":"Events that failed or were skipped during a pause and were never delivered, oldest first. Live ticks are skipped. Stops at the first failure.","security":[{"ApiKey":[]},{"BearerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"since":{"type":"string","format":"date-time","description":"Default 24 hours ago, at most 7 days"},"limit":{"type":"integer","default":50,"maximum":100},"dryRun":{"type":"boolean"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"missed":{"type":"integer"},"byEvent":{"type":"object"},"sent":{"type":"integer"},"remaining":{"type":"integer"}}}}}},"403":{"description":"Plan does not include this. See `upgradeUrl`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found on your account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhook-inbox":{"post":{"summary":"Create a hosted temporary test inbox","description":"Any plan. Lasts 24 hours. Holds 100 requests of up to 64 KB. Free and Starter can add samples; pointing a webhook at it needs Pro or Scale.","security":[{"ApiKey":[]},{"BearerKey":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"inbox":{"$ref":"#/components/schemas/Inbox"},"signingSecret":{"type":"string"},"limits":{"type":"object"},"plan":{"type":"object"}}}}}},"400":{"description":"Bad request: `error` says what is wrong, `fix` what to do","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests. See Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"List your live inboxes","security":[{"ApiKey":[]},{"BearerKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"inboxes":{"type":"array","items":{"$ref":"#/components/schemas/Inbox"}}}}}}}}}},"/webhook-inbox/{id}":{"delete":{"summary":"Delete an inbox","security":[{"ApiKey":[]},{"BearerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Not found on your account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhook-inbox/{id}/requests":{"get":{"summary":"Read stored requests","description":"Newest first. With after=<latestRequestId> only newer ones, oldest first, for polling.","security":[{"ApiKey":[]},{"BearerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"after","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":100}},{"name":"includeBody","in":"query","schema":{"type":"boolean","default":true}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Not found on your account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Clear stored requests","security":[{"ApiKey":[]},{"BearerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"cleared":{"type":"integer"}}}}}},"404":{"description":"Not found on your account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhook-inbox/{id}/stream":{"get":{"summary":"Server-sent events, one per stored request (closes after 5 minutes; reconnect)","security":[{"ApiKey":[]},{"BearerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"text/event-stream"}}}},"/webhook-inbox/{id}/sample":{"post":{"summary":"Put a real sample of an event into the inbox","description":"Any plan, any event, signed with the inbox secret and marked as a test. Below Pro, samples are at least 2 hours old. Up to 30 an hour.","security":[{"ApiKey":[]},{"BearerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["event"],"properties":{"event":{"type":"string","example":"cs2.match.completed"}}}}}},"responses":{"201":{"description":"Stored","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request: `error` says what is wrong, `fix` what to do","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found on your account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests. See Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhook-inbox/{token}":{"post":{"summary":"Receive a request (the inbox url)","description":"Public: the token is the access. Answers without echoing the body. Nothing is forwarded. A request without a valid signature is kept only in a small separate allowance (20 requests, 8 KB each).","security":[],"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"received":{"type":"boolean"},"stored":{"type":"boolean"},"id":{"type":"string"},"signatureValid":{"type":"boolean"}}}}}},"404":{"description":"No such inbox"},"410":{"description":"Expired"},"413":{"description":"Body over 256 KB"}}}}}}