Content Management API > Webhook

Create a new webhook

Body parameters

type string Required

Must be exactly "webhook".

attributes.name string Required

Unique name for the webhook

Example:

"Item type creation/update"

attributes.url string Required

The URL to be called

Example:

"https://www.example.com/webhook"

attributes.headers object Required

Additional headers that will be sent

Example:

{ "X-Foo": "Bar" }

attributes.events Required

Type: Array<object>

entity_type enum Required

The subject of webhook triggering

Example:

"item"

item_type Optional

item Optional

upload Optional

build_trigger Optional

environment Optional

maintenance_mode Optional

sso_user Optional

cda_cache_tags Optional

event_types Required

Type: Array<string>

filters Optional

Type: Array<object>, null

entity_type enum Required

item_type Optional

item Optional

build_trigger Optional

environment Optional

environment_type Optional

entity_ids Required

Type: Array<string>

attributes.custom_payload string, null Required

A custom payload

Example:

'{ "message": "{{event_type}} event triggered on {{entity_type}}!", "entity_id": "{{#entity}}{{id}}{{/entity}}"] }'

attributes.http_basic_user string, null Required

HTTP Basic Authorization username

Example:

"user"

attributes.http_basic_password string, null Required

HTTP Basic Authorization password

Example:

"password"

attributes.enabled boolean Optional

Whether the webhook is enabled and sending events or not

attributes.payload_api_version string Optional

Specifies which API version to use when serializing entities in the webhook payload

Example:

"3"

attributes.nested_items_in_payload boolean Optional

Whether the you want records present in the payload to show blocks expanded or not

attributes.auto_retry boolean Optional

If enabled, the system will attempt to retry the call several times when the webhook operation fails due to timeouts or errors.

Returns

Returns a resource object of type webhook.

Examples

1
POST https://site-api.datocms.com/webhooks HTTP/1.1
2
Authorization: Bearer YOUR-API-TOKEN
3
Accept: application/json
4
X-Api-Version: 3
5
Content-Type: application/vnd.api+json
6

7
{
8
  "data": {
9
    "type": "webhook",
10
    "attributes": {
11
      "name": "Item type creation/update",
12
      "url": "https://www.example.com/webhook",
13
      "headers": {
14
        "X-Foo": "Bar"
15
      },
16
      "events": [
17
        {
18
          "entity_type": "item",
19
          "event_types": [
20
            "update"
21
          ]
22
        }
23
      ],
24
      "custom_payload": "{ \"message\": \"{{event_type}} event triggered on {{entity_type}}!\", \"entity_id\": \"{{#entity}}{{id}}{{/entity}}\"] }",
25
      "http_basic_user": "user",
26
      "http_basic_password": "password"
27
    }
28
  }
29
}

1
curl -g 'https://site-api.datocms.com/webhooks' \
2
  -X POST \
3
  -H "Authorization: Bearer YOUR-API-TOKEN" \
4
  -H "Accept: application/json" \
5
  -H "X-Api-Version: 3" \
6
  -H "Content-Type: application/vnd.api+json" \
7
  --data-binary '{"data":{"type":"webhook","attributes":{"name":"Item type creation/update","url":"https://www.example.com/webhook","headers":{"X-Foo":"Bar"},"events":[{"entity_type":"item","event_types":["update"]}],"custom_payload":"{ \"message\": \"{{event_type}} event triggered on {{entity_type}}!\", \"entity_id\": \"{{#entity}}{{id}}{{/entity}}\"] }","http_basic_user":"user","http_basic_password":"password"}}}'

1
await fetch("https://site-api.datocms.com/webhooks", {
2
  method: "POST",
3
  headers: {
4
    Authorization: "Bearer YOUR-API-TOKEN",
5
    Accept: "application/json",
6
    "X-Api-Version": "3",
7
    "Content-Type": "application/vnd.api+json",
8
  },
9
  body: JSON.stringify({
10
    data: {
11
      type: "webhook",
12
      attributes: {
13
        name: "Item type creation/update",
14
        url: "https://www.example.com/webhook",
15
        headers: { "X-Foo": "Bar" },
16
        events: [{ entity_type: "item", event_types: ["update"] }],
17
        custom_payload:
18
          '{ "message": "{{event_type}} event triggered on {{entity_type}}!", "entity_id": "{{#entity}}{{id}}{{/entity}}"] }',
19
        http_basic_user: "user",
20
        http_basic_password: "password",
21
      },
22
    },
23
  }),
24
});

1
HTTP/1.1 200 OK
2
Content-Type: application/json
3
Cache-Control: cache-control: max-age=0, private, must-revalidate
4
X-RateLimit-Limit: 30
5
X-RateLimit-Remaining: 28
6

7
{
8
  "data": {
9
    "type": "webhook",
10
    "id": "312",
11
    "attributes": {
12
      "name": "Item type creation/update",
13
      "url": "https://www.example.com/webhook",
14
      "enabled": true,
15
      "headers": {
16
        "X-Foo": "Bar"
17
      },
18
      "events": [
19
        {
20
          "entity_type": "item",
21
          "event_types": [
22
            "update"
23
          ]
24
        }
25
      ],
26
      "http_basic_user": "user",
27
      "http_basic_password": "password",
28
      "custom_payload": "{ \"message\": \"{{event_type}} event triggered on {{entity_type}}!\", \"entity_id\": \"{{#entity}}{{id}}{{/entity}}\"] }",
29
      "payload_api_version": "3",
30
      "nested_items_in_payload": true,
31
      "auto_retry": true
32
    }
33
  }
34
}