{"id":"event-delivery-webhooks","title":"Event delivery and webhooks","description":"Create, test, and observe webhook deliveries for approved outbound integrations.","lastUpdated":"2026-03-23","sections":[{"id":"webhooks-collection","title":"GET/POST /v1/webhooks · Create and list webhooks","content":"Route: GET/POST /v1/webhooks\nHost: https://auth.knogin.com\nAuth: Bearer token\nAudience: External integrators\nStability: Stable\n\nManages outbound webhook subscriptions used to deliver approved event notifications to an external system.\n\nIntegration notes:\n- Create subscriptions only for events your integration has been approved to receive.\n- Outbound webhook secrets should be stored and rotated like any other integration credential.","codeExamples":[{"language":"bash","code":"curl -X POST https://auth.knogin.com/v1/webhooks \\\n  -H \"Authorization: Bearer <access-token>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"url\": \"https://integrator.example/webhooks/argus\",\n    \"events\": [\"incident.updated\"],\n    \"secret\": \"<signing-secret>\"\n  }'","description":"Request example"},{"language":"json","code":"{\n  \"id\": \"wh_123\",\n  \"url\": \"https://integrator.example/webhooks/argus\",\n  \"events\": [\"incident.updated\"]\n}","description":"Response example"}]},{"id":"webhooks-item","title":"GET/PUT/DELETE /v1/webhooks/{webhook_id} · Inspect, update, or delete a webhook","content":"Route: GET/PUT/DELETE /v1/webhooks/{webhook_id}\nHost: https://auth.knogin.com\nAuth: Bearer token\nAudience: External integrators\nStability: Stable\n\nManages an individual webhook subscription by identifier.\n\nIntegration notes:\n- Use update operations to rotate secrets or adjust event selections without recreating the subscription.","codeExamples":[{"language":"bash","code":"curl -X PUT https://auth.knogin.com/v1/webhooks/wh_123 \\\n  -H \"Authorization: Bearer <access-token>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"events\": [\"incident.updated\", \"incident.closed\"]\n  }'","description":"Request example"},{"language":"json","code":"{\n  \"id\": \"wh_123\",\n  \"events\": [\"incident.updated\", \"incident.closed\"]\n}","description":"Response example"}]},{"id":"webhooks-deliveries","title":"GET /v1/webhooks/{webhook_id}/deliveries · Review delivery attempts","content":"Route: GET /v1/webhooks/{webhook_id}/deliveries\nHost: https://auth.knogin.com\nAuth: Bearer token\nAudience: External integrators\nStability: Stable\n\nReturns historical delivery attempts for a webhook so integrators can debug retries and downstream failures.\n\nIntegration notes:\n- Use delivery history instead of internal logs to diagnose receiver behavior.\n- Delivery metadata is limited to the webhook in scope.","codeExamples":[{"language":"bash","code":"curl https://auth.knogin.com/v1/webhooks/wh_123/deliveries \\\n  -H \"Authorization: Bearer <access-token>\"","description":"Request example"},{"language":"json","code":"{\n  \"deliveries\": [\n    {\n      \"id\": \"dlv_123\",\n      \"status\": \"succeeded\",\n      \"attempted_at\": \"2026-03-23T12:00:00Z\"\n    }\n  ]\n}","description":"Response example"}]},{"id":"webhooks-test","title":"POST /v1/webhooks/{webhook_id}/test · Send a test webhook","content":"Route: POST /v1/webhooks/{webhook_id}/test\nHost: https://auth.knogin.com\nAuth: Bearer token\nAudience: External integrators\nStability: Stable\n\nTriggers a synthetic delivery to validate receiver configuration before enabling production traffic.\n\nIntegration notes:\n- Use test deliveries when rotating secrets or validating a new endpoint.","codeExamples":[{"language":"bash","code":"curl -X POST https://auth.knogin.com/v1/webhooks/wh_123/test \\\n  -H \"Authorization: Bearer <access-token>\"","description":"Request example"},{"language":"json","code":"{\n  \"delivery_id\": \"dlv_test_123\",\n  \"status\": \"queued\"\n}","description":"Response example"}]}],"relatedTopics":["identity-app-registration","oauth-service-tokens","jwks-token-verification","graphql-transport-contract"],"markdown":"# Event delivery and webhooks\n\nCreate, test, and observe webhook deliveries for approved outbound integrations.\n\n## GET/POST /v1/webhooks · Create and list webhooks\n\nRoute: GET/POST /v1/webhooks\nHost: https://auth.knogin.com\nAuth: Bearer token\nAudience: External integrators\nStability: Stable\n\nManages outbound webhook subscriptions used to deliver approved event notifications to an external system.\n\nIntegration notes:\n- Create subscriptions only for events your integration has been approved to receive.\n- Outbound webhook secrets should be stored and rotated like any other integration credential.\n\nRequest example\n\n```bash\ncurl -X POST https://auth.knogin.com/v1/webhooks \\\n  -H \"Authorization: Bearer <access-token>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"url\": \"https://integrator.example/webhooks/argus\",\n    \"events\": [\"incident.updated\"],\n    \"secret\": \"<signing-secret>\"\n  }'\n```\n\nResponse example\n\n```json\n{\n  \"id\": \"wh_123\",\n  \"url\": \"https://integrator.example/webhooks/argus\",\n  \"events\": [\"incident.updated\"]\n}\n```\n\n## GET/PUT/DELETE /v1/webhooks/{webhook_id} · Inspect, update, or delete a webhook\n\nRoute: GET/PUT/DELETE /v1/webhooks/{webhook_id}\nHost: https://auth.knogin.com\nAuth: Bearer token\nAudience: External integrators\nStability: Stable\n\nManages an individual webhook subscription by identifier.\n\nIntegration notes:\n- Use update operations to rotate secrets or adjust event selections without recreating the subscription.\n\nRequest example\n\n```bash\ncurl -X PUT https://auth.knogin.com/v1/webhooks/wh_123 \\\n  -H \"Authorization: Bearer <access-token>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"events\": [\"incident.updated\", \"incident.closed\"]\n  }'\n```\n\nResponse example\n\n```json\n{\n  \"id\": \"wh_123\",\n  \"events\": [\"incident.updated\", \"incident.closed\"]\n}\n```\n\n## GET /v1/webhooks/{webhook_id}/deliveries · Review delivery attempts\n\nRoute: GET /v1/webhooks/{webhook_id}/deliveries\nHost: https://auth.knogin.com\nAuth: Bearer token\nAudience: External integrators\nStability: Stable\n\nReturns historical delivery attempts for a webhook so integrators can debug retries and downstream failures.\n\nIntegration notes:\n- Use delivery history instead of internal logs to diagnose receiver behavior.\n- Delivery metadata is limited to the webhook in scope.\n\nRequest example\n\n```bash\ncurl https://auth.knogin.com/v1/webhooks/wh_123/deliveries \\\n  -H \"Authorization: Bearer <access-token>\"\n```\n\nResponse example\n\n```json\n{\n  \"deliveries\": [\n    {\n      \"id\": \"dlv_123\",\n      \"status\": \"succeeded\",\n      \"attempted_at\": \"2026-03-23T12:00:00Z\"\n    }\n  ]\n}\n```\n\n## POST /v1/webhooks/{webhook_id}/test · Send a test webhook\n\nRoute: POST /v1/webhooks/{webhook_id}/test\nHost: https://auth.knogin.com\nAuth: Bearer token\nAudience: External integrators\nStability: Stable\n\nTriggers a synthetic delivery to validate receiver configuration before enabling production traffic.\n\nIntegration notes:\n- Use test deliveries when rotating secrets or validating a new endpoint.\n\nRequest example\n\n```bash\ncurl -X POST https://auth.knogin.com/v1/webhooks/wh_123/test \\\n  -H \"Authorization: Bearer <access-token>\"\n```\n\nResponse example\n\n```json\n{\n  \"delivery_id\": \"dlv_test_123\",\n  \"status\": \"queued\"\n}\n```\n\n## Related Topics\n\n- [Identity and app registration](https://knogin.com/api/docs/identity-app-registration)\n- [OAuth and service tokens](https://knogin.com/api/docs/oauth-service-tokens)\n- [JWKS and token verification](https://knogin.com/api/docs/jwks-token-verification)\n- [GraphQL transport contract](https://knogin.com/api/docs/graphql-transport-contract)","metadata":{"readingTime":"8 min","difficulty":"intermediate","tags":["integrations","api","oauth","webhooks","graphql"]}}