# Webhooks Manage HTTP webhooks for projects. Webhooks allow you to receive HTTP POST notifications when certain events occur in your test runs: * **RUN\_FINISH**: Run completed (passed or failed) * **RUN\_START**: Run started * **RUN\_TIMEOUT**: Run timed out * **RUN\_CANCELED**: Run was cancelled Webhooks are useful for integrating with external tools like n8n, Zapier, or custom automation platforms. ## List webhooks > Get all generic webhooks for a project ```json {"openapi":"3.0.2","info":{"title":"Currents REST API","version":"1.0.0"},"tags":[{"name":"Webhooks","description":"Manage HTTP webhooks for projects.\n\nWebhooks allow you to receive HTTP POST notifications when certain events occur in your test runs:\n- **RUN_FINISH**: Run completed (passed or failed)\n- **RUN_START**: Run started\n- **RUN_TIMEOUT**: Run timed out\n- **RUN_CANCELED**: Run was cancelled\n\nWebhooks are useful for integrating with external tools like n8n, Zapier, or custom automation platforms."}],"servers":[{"url":"https://api.currents.dev/v1","description":"Production API"},{"url":"https://api-staging.currents.dev/v1","description":"Staging API"},{"url":"http://localhost:4000/v1","description":"Local development"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key authentication using Bearer token"}},"parameters":{"ProjectIdQuery":{"name":"projectId","in":"query","required":true,"description":"The project ID","schema":{"type":"string"}}},"schemas":{"WebhookListResponse":{"type":"object","required":["status","data"],"properties":{"status":{"type":"string","enum":["OK"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}}}},"Webhook":{"type":"object","required":["hookId","projectId","url","hookEvents"],"properties":{"hookId":{"type":"string","format":"uuid","description":"Unique identifier for the webhook"},"projectId":{"type":"string","description":"Project this webhook belongs to"},"url":{"type":"string","format":"uri","maxLength":2048,"description":"URL to send webhook POST requests to"},"headers":{"type":"string","nullable":true,"maxLength":4096,"description":"Custom headers as a JSON object string (e.g., {\"Authorization\": \"Bearer token\"})"},"hookEvents":{"type":"array","items":{"$ref":"#/components/schemas/HookEvent"},"description":"Events that trigger this webhook"},"label":{"type":"string","nullable":true,"maxLength":255,"description":"Human-readable label for the webhook"},"createdAt":{"type":"string","format":"date-time","nullable":true,"description":"When the webhook was created"},"updatedAt":{"type":"string","format":"date-time","nullable":true,"description":"When the webhook was last updated"}}},"HookEvent":{"type":"string","enum":["RUN_FINISH","RUN_START","RUN_TIMEOUT","RUN_CANCELED"],"description":"The event that triggers the webhook:\n- `RUN_FINISH`: Run completed (passed or failed)\n- `RUN_START`: Run started\n- `RUN_TIMEOUT`: Run timed out\n- `RUN_CANCELED`: Run was cancelled"},"ErrorResponse":{"type":"object","required":["status","error"],"properties":{"status":{"type":"string","enum":["FAILED"]},"error":{"type":"string","description":"Error message"}}}},"responses":{"BadRequest":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/webhooks":{"get":{"summary":"List webhooks","description":"Get all generic webhooks for a project","operationId":"listWebhooks","tags":["Webhooks"],"parameters":[{"$ref":"#/components/parameters/ProjectIdQuery"}],"responses":{"200":{"description":"List of webhooks","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookListResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}}}} ``` ## Create webhook > Create a new generic webhook for a project ```json {"openapi":"3.0.2","info":{"title":"Currents REST API","version":"1.0.0"},"tags":[{"name":"Webhooks","description":"Manage HTTP webhooks for projects.\n\nWebhooks allow you to receive HTTP POST notifications when certain events occur in your test runs:\n- **RUN_FINISH**: Run completed (passed or failed)\n- **RUN_START**: Run started\n- **RUN_TIMEOUT**: Run timed out\n- **RUN_CANCELED**: Run was cancelled\n\nWebhooks are useful for integrating with external tools like n8n, Zapier, or custom automation platforms."}],"servers":[{"url":"https://api.currents.dev/v1","description":"Production API"},{"url":"https://api-staging.currents.dev/v1","description":"Staging API"},{"url":"http://localhost:4000/v1","description":"Local development"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key authentication using Bearer token"}},"parameters":{"ProjectIdQuery":{"name":"projectId","in":"query","required":true,"description":"The project ID","schema":{"type":"string"}}},"schemas":{"CreateWebhookRequest":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","maxLength":2048,"description":"URL to send webhook POST requests to"},"headers":{"type":"string","maxLength":4096,"nullable":true,"description":"Custom headers as a JSON object string (e.g., {\"Authorization\": \"Bearer token\"})"},"hookEvents":{"type":"array","items":{"$ref":"#/components/schemas/HookEvent"},"default":[],"description":"Events that trigger this webhook"},"label":{"type":"string","minLength":1,"maxLength":255,"nullable":true,"description":"Human-readable label for the webhook"}}},"HookEvent":{"type":"string","enum":["RUN_FINISH","RUN_START","RUN_TIMEOUT","RUN_CANCELED"],"description":"The event that triggers the webhook:\n- `RUN_FINISH`: Run completed (passed or failed)\n- `RUN_START`: Run started\n- `RUN_TIMEOUT`: Run timed out\n- `RUN_CANCELED`: Run was cancelled"},"WebhookResponse":{"type":"object","required":["status","data"],"properties":{"status":{"type":"string","enum":["OK"]},"data":{"$ref":"#/components/schemas/Webhook"}}},"Webhook":{"type":"object","required":["hookId","projectId","url","hookEvents"],"properties":{"hookId":{"type":"string","format":"uuid","description":"Unique identifier for the webhook"},"projectId":{"type":"string","description":"Project this webhook belongs to"},"url":{"type":"string","format":"uri","maxLength":2048,"description":"URL to send webhook POST requests to"},"headers":{"type":"string","nullable":true,"maxLength":4096,"description":"Custom headers as a JSON object string (e.g., {\"Authorization\": \"Bearer token\"})"},"hookEvents":{"type":"array","items":{"$ref":"#/components/schemas/HookEvent"},"description":"Events that trigger this webhook"},"label":{"type":"string","nullable":true,"maxLength":255,"description":"Human-readable label for the webhook"},"createdAt":{"type":"string","format":"date-time","nullable":true,"description":"When the webhook was created"},"updatedAt":{"type":"string","format":"date-time","nullable":true,"description":"When the webhook was last updated"}}},"ErrorResponse":{"type":"object","required":["status","error"],"properties":{"status":{"type":"string","enum":["FAILED"]},"error":{"type":"string","description":"Error message"}}}},"responses":{"BadRequest":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/webhooks":{"post":{"summary":"Create webhook","description":"Create a new generic webhook for a project","operationId":"createWebhook","tags":["Webhooks"],"parameters":[{"$ref":"#/components/parameters/ProjectIdQuery"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebhookRequest"}}}},"responses":{"201":{"description":"Webhook created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}}}} ``` ## Get webhook > Get a specific webhook by ID. The hookId is globally unique, so projectId is not required. ```json {"openapi":"3.0.2","info":{"title":"Currents REST API","version":"1.0.0"},"tags":[{"name":"Webhooks","description":"Manage HTTP webhooks for projects.\n\nWebhooks allow you to receive HTTP POST notifications when certain events occur in your test runs:\n- **RUN_FINISH**: Run completed (passed or failed)\n- **RUN_START**: Run started\n- **RUN_TIMEOUT**: Run timed out\n- **RUN_CANCELED**: Run was cancelled\n\nWebhooks are useful for integrating with external tools like n8n, Zapier, or custom automation platforms."}],"servers":[{"url":"https://api.currents.dev/v1","description":"Production API"},{"url":"https://api-staging.currents.dev/v1","description":"Staging API"},{"url":"http://localhost:4000/v1","description":"Local development"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key authentication using Bearer token"}},"parameters":{"HookIdPath":{"name":"hookId","in":"path","required":true,"description":"The webhook ID (UUID)","schema":{"type":"string","format":"uuid"}}},"schemas":{"WebhookResponse":{"type":"object","required":["status","data"],"properties":{"status":{"type":"string","enum":["OK"]},"data":{"$ref":"#/components/schemas/Webhook"}}},"Webhook":{"type":"object","required":["hookId","projectId","url","hookEvents"],"properties":{"hookId":{"type":"string","format":"uuid","description":"Unique identifier for the webhook"},"projectId":{"type":"string","description":"Project this webhook belongs to"},"url":{"type":"string","format":"uri","maxLength":2048,"description":"URL to send webhook POST requests to"},"headers":{"type":"string","nullable":true,"maxLength":4096,"description":"Custom headers as a JSON object string (e.g., {\"Authorization\": \"Bearer token\"})"},"hookEvents":{"type":"array","items":{"$ref":"#/components/schemas/HookEvent"},"description":"Events that trigger this webhook"},"label":{"type":"string","nullable":true,"maxLength":255,"description":"Human-readable label for the webhook"},"createdAt":{"type":"string","format":"date-time","nullable":true,"description":"When the webhook was created"},"updatedAt":{"type":"string","format":"date-time","nullable":true,"description":"When the webhook was last updated"}}},"HookEvent":{"type":"string","enum":["RUN_FINISH","RUN_START","RUN_TIMEOUT","RUN_CANCELED"],"description":"The event that triggers the webhook:\n- `RUN_FINISH`: Run completed (passed or failed)\n- `RUN_START`: Run started\n- `RUN_TIMEOUT`: Run timed out\n- `RUN_CANCELED`: Run was cancelled"},"ErrorResponse":{"type":"object","required":["status","error"],"properties":{"status":{"type":"string","enum":["FAILED"]},"error":{"type":"string","description":"Error message"}}}},"responses":{"BadRequest":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/webhooks/{hookId}":{"get":{"summary":"Get webhook","description":"Get a specific webhook by ID. The hookId is globally unique, so projectId is not required.","operationId":"getWebhook","tags":["Webhooks"],"parameters":[{"$ref":"#/components/parameters/HookIdPath"}],"responses":{"200":{"description":"Webhook details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}}}} ``` ## Update webhook > Update an existing webhook. Supports partial updates. The hookId is globally unique, so projectId is not required. ```json {"openapi":"3.0.2","info":{"title":"Currents REST API","version":"1.0.0"},"tags":[{"name":"Webhooks","description":"Manage HTTP webhooks for projects.\n\nWebhooks allow you to receive HTTP POST notifications when certain events occur in your test runs:\n- **RUN_FINISH**: Run completed (passed or failed)\n- **RUN_START**: Run started\n- **RUN_TIMEOUT**: Run timed out\n- **RUN_CANCELED**: Run was cancelled\n\nWebhooks are useful for integrating with external tools like n8n, Zapier, or custom automation platforms."}],"servers":[{"url":"https://api.currents.dev/v1","description":"Production API"},{"url":"https://api-staging.currents.dev/v1","description":"Staging API"},{"url":"http://localhost:4000/v1","description":"Local development"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key authentication using Bearer token"}},"parameters":{"HookIdPath":{"name":"hookId","in":"path","required":true,"description":"The webhook ID (UUID)","schema":{"type":"string","format":"uuid"}}},"schemas":{"UpdateWebhookRequest":{"type":"object","properties":{"url":{"type":"string","format":"uri","maxLength":2048,"description":"URL to send webhook POST requests to"},"headers":{"type":"string","maxLength":4096,"nullable":true,"description":"Custom headers as a JSON object string (e.g., {\"Authorization\": \"Bearer token\"})"},"hookEvents":{"type":"array","items":{"$ref":"#/components/schemas/HookEvent"},"description":"Events that trigger this webhook"},"label":{"type":"string","minLength":1,"maxLength":255,"nullable":true,"description":"Human-readable label for the webhook"}}},"HookEvent":{"type":"string","enum":["RUN_FINISH","RUN_START","RUN_TIMEOUT","RUN_CANCELED"],"description":"The event that triggers the webhook:\n- `RUN_FINISH`: Run completed (passed or failed)\n- `RUN_START`: Run started\n- `RUN_TIMEOUT`: Run timed out\n- `RUN_CANCELED`: Run was cancelled"},"WebhookResponse":{"type":"object","required":["status","data"],"properties":{"status":{"type":"string","enum":["OK"]},"data":{"$ref":"#/components/schemas/Webhook"}}},"Webhook":{"type":"object","required":["hookId","projectId","url","hookEvents"],"properties":{"hookId":{"type":"string","format":"uuid","description":"Unique identifier for the webhook"},"projectId":{"type":"string","description":"Project this webhook belongs to"},"url":{"type":"string","format":"uri","maxLength":2048,"description":"URL to send webhook POST requests to"},"headers":{"type":"string","nullable":true,"maxLength":4096,"description":"Custom headers as a JSON object string (e.g., {\"Authorization\": \"Bearer token\"})"},"hookEvents":{"type":"array","items":{"$ref":"#/components/schemas/HookEvent"},"description":"Events that trigger this webhook"},"label":{"type":"string","nullable":true,"maxLength":255,"description":"Human-readable label for the webhook"},"createdAt":{"type":"string","format":"date-time","nullable":true,"description":"When the webhook was created"},"updatedAt":{"type":"string","format":"date-time","nullable":true,"description":"When the webhook was last updated"}}},"ErrorResponse":{"type":"object","required":["status","error"],"properties":{"status":{"type":"string","enum":["FAILED"]},"error":{"type":"string","description":"Error message"}}}},"responses":{"BadRequest":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/webhooks/{hookId}":{"put":{"summary":"Update webhook","description":"Update an existing webhook. Supports partial updates. The hookId is globally unique, so projectId is not required.","operationId":"updateWebhook","tags":["Webhooks"],"parameters":[{"$ref":"#/components/parameters/HookIdPath"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWebhookRequest"}}}},"responses":{"200":{"description":"Webhook updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}}}} ``` ## Delete webhook > Delete a webhook. The hookId is globally unique, so projectId is not required. ```json {"openapi":"3.0.2","info":{"title":"Currents REST API","version":"1.0.0"},"tags":[{"name":"Webhooks","description":"Manage HTTP webhooks for projects.\n\nWebhooks allow you to receive HTTP POST notifications when certain events occur in your test runs:\n- **RUN_FINISH**: Run completed (passed or failed)\n- **RUN_START**: Run started\n- **RUN_TIMEOUT**: Run timed out\n- **RUN_CANCELED**: Run was cancelled\n\nWebhooks are useful for integrating with external tools like n8n, Zapier, or custom automation platforms."}],"servers":[{"url":"https://api.currents.dev/v1","description":"Production API"},{"url":"https://api-staging.currents.dev/v1","description":"Staging API"},{"url":"http://localhost:4000/v1","description":"Local development"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key authentication using Bearer token"}},"parameters":{"HookIdPath":{"name":"hookId","in":"path","required":true,"description":"The webhook ID (UUID)","schema":{"type":"string","format":"uuid"}}},"schemas":{"WebhookDeleteResponse":{"type":"object","required":["status","data"],"properties":{"status":{"type":"string","enum":["OK"]},"data":{"type":"object","required":["hookId","projectId"],"properties":{"hookId":{"type":"string","format":"uuid","description":"ID of the deleted webhook"},"projectId":{"type":"string","description":"Project the webhook belonged to"}}}}},"ErrorResponse":{"type":"object","required":["status","error"],"properties":{"status":{"type":"string","enum":["FAILED"]},"error":{"type":"string","description":"Error message"}}}},"responses":{"BadRequest":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/webhooks/{hookId}":{"delete":{"summary":"Delete webhook","description":"Delete a webhook. The hookId is globally unique, so projectId is not required.","operationId":"deleteWebhook","tags":["Webhooks"],"parameters":[{"$ref":"#/components/parameters/HookIdPath"}],"responses":{"200":{"description":"Webhook deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDeleteResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}}}} ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.currents.dev/api/resources/webhooks.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.