Last updated on 1st April 2026

Creating an integration via API

This method creates a new integration for a project.

Tip: You can explore and test this endpoint interactively using our OpenAPI documentation.

URL

/projects/<project>/integrations

Replace <project> with either the permalink or identifier of the project.

HTTP Method

POST

Allowed Integration Types

The following integration types can be created via the API:

  • http_req - HTTP Request
  • cloudflare - Cloudflare
  • new_relic - New Relic
  • rollbar - Rollbar
  • honeybadger - Honeybadger
  • microsoft_teams - Microsoft Teams
  • codebase - Codebase
  • sentry - Sentry
  • bugsnag - Bugsnag
  • slack_oauth - Slack (OAuth)
  • discord - Discord (OAuth)

Supported Parameters

  • hook_type (required) - The integration type (see allowed types above)
  • name (required) - A display name for the integration
  • send_on_completion - Send notification on successful deployment (default: false)
  • send_on_failure - Send notification on failed deployment (default: false)
  • send_on_start - Send notification when deployment starts (default: false)
  • properties - A hash of type-specific configuration (see below)

Properties by Type

Each integration type requires different properties. For example:

  • http_req: url
  • cloudflare: zone_id, path_prefix
  • new_relic: application_id, api_key
  • rollbar: token, environment
  • honeybadger: api_key, environment
  • microsoft_teams: url, team
  • sentry: hook_version (required: cloud or on_premise), project, environment, token, organization_slug (cloud) or url (on-premise)
  • bugsnag: hook_version (required: cloud or on_premise), api_key, url (on-premise only)
  • codebase: account, project, repository, username, api_key

Example cURL Request

curl -H "Content-type: application/json" \
-H "Accept: application/json" \
--user your-email@example.com:your-api-key \
-X POST \
-d '{
  "integration": {
    "hook_type": "http_req",
    "name": "Deploy webhook",
    "send_on_completion": true,
    "send_on_failure": true,
    "properties": {
      "url": "https://example.com/webhook"
    }
  }
}' \
https://test.deployhq.com/projects/my-project/integrations

Example Response

{
    "identifier": "a3f1b2c4-5d6e-7f8a-9b0c-1d2e3f4a5b6c",
    "hook_type": "http_req",
    "name": "Deploy webhook",
    "send_on_start": false,
    "send_on_completion": true,
    "send_on_failure": true,
    "created_at": "2026-03-31T10:30:00.000Z",
    "updated_at": "2026-03-31T10:30:00.000Z"
}

OAuth Integrations (Slack, Discord)

When creating a slack_oauth or discord integration, the response will include an authorization URL instead of the integration details:

{
    "auth_required": true,
    "auth_url": "https://deployhq.com/auth/slack/..."
}

The user must open the auth_url in a browser to authorize the integration with the third-party service. Once authorized, the integration becomes active.