Connect Semaphore to your tools

Use a webhook integration when an external event should select a predefined Task Template and map request values into accepted inputs. Use the REST API when your application needs a more explicit resource and execution workflow, such as launching a task and reading its status. In either case, the automation runs through Semaphore's configured execution model. Choose the approach based on what the caller needs to send and track.

A project alias evaluates the configured matchers across its integrations and can start those that match the request. An integration-specific alias addresses one integration directly without evaluating its matchers. This matters if you expect a branch or event-type rule to control execution. Choose the endpoint deliberately and test both matching and non-matching payloads rather than assuming the same filter applies to every alias path.

Configure extractors to read the relevant request headers or body fields and map them to documented environment values or task parameters. Parameter destinations must align with the template's accepted prompts. Keep the mapping specific: a release version should become the intended input, not an unrestricted command fragment. Validate the value in your automation where its meaning requires validation, and test missing or unexpected fields before production use.

An API token acts with the permissions of its Semaphore user. Use an identity whose project access matches the integration's intended operations, and protect the token wherever the caller stores it. The API is not a bypass around project authorization. For webhook integrations, also configure the documented request authentication and endpoint exposure deliberately. Keep caller authentication separate from the credentials that the resulting task uses to reach infrastructure.

For a REST API flow, retain the task identifier returned by the documented operation and use the corresponding API methods to inspect its state and output. A successful request means the execution was requested, not that infrastructure work finished successfully. Your service should distinguish request errors, waiting or running tasks, and completed outcomes. Link engineers to the task when they need to investigate the actual execution evidence.

Do not assume exactly-once execution or durable delivery guarantees. An external service may retry a request after a timeout even when the first request reached Semaphore. Design duplicate handling and retry decisions around the operation's consequences, and make the underlying automation idempotent where appropriate. Keep a correlation between the originating event and the execution your service tracks so engineers can understand repeated or uncertain deliveries.

The reference on this site renders the Swagger/OpenAPI document published with the Semaphore release, so the operations, paths and schemas you see correspond to a specific version rather than to a hand-written summary. Browse it by resource at /api-docs/, or read the raw document if you generate a client from it. Always check the specification for the version you actually run, because endpoints and request schemas can change between releases.

The calling system has to reach your Semaphore instance, but that does not have to mean the public internet. A private network, VPN or internal load balancer is enough when the caller runs inside it. Our own matcher and extractor verification used a loopback-only listener with authentication disabled, which is not a model for an exposed endpoint. Whenever the alias can be reached from outside your trusted network, configure a supported authentication method and restrict exposure at the network layer too.

Point the integration at a harmless Task Template first, then send the payloads yourself with curl or any HTTP client. Send a non-matching body and confirm that no task appears, then send a matching body and confirm that exactly one task starts. Open that task's Details view: it records the integration as the source, and the extracted values are visible to the run. This is the same sequence we used locally, and it catches a wrong matcher key before an external service depends on it.

Yes. The REST API covers projects, repositories, inventories, credentials, Variable Groups, Task Templates and other automation resources. Your portal or infrastructure service can configure them, start tasks and read execution status and output. Pro also exposes Workflow runs and approvals through the API, so a CI/CD pipeline can start a complete multi-step operation. Use the OpenAPI reference for endpoint parameters and response schemas.