# Create outgoing webhook 

Returns either a newly created Outgoing Webhook integration, or validation errors.

[endpoint]
base_url = "https://uptime.betterstack.com"
path = "/api/v2/outgoing-webhooks"
method = "POST"

[[body_param]]
name = "team_name"
description = "Required if using [global API token](https://betterstack.com/docs/uptime/api/getting-started-with-uptime-api/#get-a-global-api-token) to specify the team which should own the resource."
required = false
type = "string"

[[body_param]]
name = "name"
description = "The name of the Outgoing Webhook integration that you can see in the dashboard."
required = false
type = "string"

[[body_param]]
name = "url"
description = "The URL of the Outgoing Webhook integration."
required = true
type = "string"

[[body_param]]
name = "trigger_type"
description = "The type of trigger for the Outgoing Webhook integration. Possible values are `on_call_change`, `incident_change` and `monitor_change`."
required = true
type = "string"

[[body_param]]
name = "on_incident_started"
description = "Whether to trigger the Outgoing Webhook integration when an incident starts. Only applicable if `trigger_type` is `incident_change`."
required = false
type = "boolean"

[[body_param]]
name = "on_incident_acknowledged"
description = "Whether to trigger the Outgoing Webhook integration when an incident is acknowledged. Only applicable if `trigger_type` is `incident_change`."
required = false
type = "boolean"

[[body_param]]
name = "on_incident_resolved"
description = "Whether to trigger the Outgoing Webhook integration when an incident is resolved. Only applicable if `trigger_type` is `incident_change`."
required = false
type = "boolean"

[[body_param]]
name = "on_incident_reopened"
description = "Whether to trigger the Outgoing Webhook integration when an incident is reopened. Only applicable if `trigger_type` is `incident_change`."
required = false
type = "boolean"

[[body_param]]
name = "custom_webhook_template_attributes"
description = "Use this to specify the custom webhook template attributes. See below."
required = false
type = "object"

[[body_param]]
name = "custom_webhook_template_attributes.http_method"
description = "The HTTP method to use when sending the webhook. Possible values are `get`, `post`, `put`, `patch` and `head`."
required = false
type = "string"

[[body_param]]
name = "custom_webhook_template_attributes.auth_username"
description = "The username to use for basic authentication."
required = false
type = "string"

[[body_param]]
name = "custom_webhook_template_attributes.auth_password"
description = "The password to use for basic authentication."
required = false
type = "string"

[[body_param]]
name = "custom_webhook_template_attributes.headers_template"
description = '''
The headers to send with the webhook.
<br/><br/>

```json
[label Each header is an object with `name` and `value` keys.]
{
  "custom_webhook_template_attributes": {
    "headers_template": [
      { "name": "Content-Type", "value": "application/json" },
      { "name": "X-Custom-Header", "value": "Custom-Value" }
    ]
  }
}
```
'''
required = false
type = "array"

[[body_param]]
name = "custom_webhook_template_attributes.body_template"
description = '''
The body to send with the webhook. The value can be a stringified JSON or a JSON object.
<br/><br/>

```json
[label Using JSON object]
{
  "custom_webhook_template_attributes": {
    "body_template": {
      "data": {
        "id": "$INCIDENT_ID",
        "type": "incident",
        "attributes": {
          "name": "$NAME",
          "url": "$URL",
          "http_method": "$HTTP_METHOD",
          "screenshot_url": "$SCREENSHOT_URL"
        }
      }
    }
  }
}
```

```json
[label Using stringified JSON]
{
  "custom_webhook_template_attributes": {
    "body_template": "{\"data\":{\"id\":\"$INCIDENT_ID\",\"type\":\"incident\",\"attributes\":{\"name\":\"$NAME\",\"url\":\"$URL\",\"http_method\":\"$HTTP_METHOD\",\"screenshot_url\":\"$SCREENSHOT_URL\"}}}"
  }
}
```

When not specified, the default template is used. Each `trigger_type` has its own default template:
<br/><br/>


```json
[label Default template for `on_call_change`]
{
  "data":{
    "message": "$MESSAGE",
    "emails": $EMAILS_JSON_ARRAY,
    "calendar_id": $ON_CALL_CALENDAR_ID,
    "calendar_name": "$ON_CALL_CALENDAR_NAME",
    "primary_calendar": $DEFAULT_ON_CALL_CALENDAR
  }
}
```

```json
[label Default template for `incident_change`]
{
  "data": {
    "id": "$INCIDENT_ID",
    "type": "incident",
    "attributes": {
      "name": "$NAME",
      "url": "$URL",
      "http_method": "$HTTP_METHOD",
      "cause": "$CAUSE",
      "started_at": "$STARTED_AT",
      "acknowledged_at": "$ACKNOWLEDGED_AT",
      "resolved_at": "$RESOLVED_AT",
      "response_content": "$RESPONSE_CONTENT",
      "response_url": "$RESPONSE_URL",
      "screenshot_url": "$SCREENSHOT_URL"
    }
  }
}
```

```json
[label Default template for `monitor_change`]
{
  "data":{
    "id": "$MONITOR_ID",
    "type": "monitor",
    "attributes":{
      "url": "$URL",
      "pronounceable_name": "$PRONOUNCEABLE_NAME",
      "monitor_type": "$MONITOR_TYPE",
      "required_keyword": "$REQUIRED_KEYWORD",
      "verify_ssl": $VERIFY_SSL,
      "check_frequency": $CHECK_FREQUENCY,
      "call": $CALL,
      "sms": $SMS,
      "email": $EMAIL,
      "team_wait": "$TEAM_WAIT",
      "http_method": "$HTTP_METHOD",
      "request_timeout": "$REQUEST_TIMEOUT",
      "recovery_period": "$RECOVERY_PERIOD",
      "request_body": "$REQUEST_BODY",
      "paused_at": "$PAUSED_AT",
      "last_checked_at": "$LAST_CHECKED_AT"
    }
  }
}
```

'''
required = false
type = "string|JSON"

[[header]]
name = "Authorization"
description = "Bearer `$TOKEN`"
required = true
type = "string"

[[header]]
name = "Content_Type"
description = "application/json"
required = false
type = "string"
[/endpoint]

[responses]
[[response]]
status = 201
description = '''Returns newly created Outgoing Webhook integration'''
body = '''{
  "data": {
    "id": "16",
    "type": "outgoing_webhook",
    "attributes": {
      "name": "test",
      "url": "https://example.com",
      "trigger_type": "on_call_change",
      "team_name": "My team"
    },
    "relationships": {
      "custom_webhook_template": {
        "data": null
      }
    }
  },
  "included": []
}'''

[/responses]

#### Example cURL

```shell
[label Example]
curl -X "POST" "https://uptime.betterstack.com/api/v2/outgoing-webhooks/" \
     -H "Authorization: Bearer $TOKEN" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "name": "Test",
  "url": "https://example.com",
  "trigger_type": "on_call_change"
}'
```

[info]
#### Looking for the details of a specific parameter?
Explore [the list of all Outgoing Webhook integration API parameters](https://betterstack.com/docs/uptime/api/outgoing-webhook-integrations-response-params/)
[/info]