directus/docs/reference/system/webhooks.md

description, readTime, pageClass

description	readTime	pageClass
REST and GraphQL API documentation on the Webhooks collection in Directus.	5 min read	page-reference

Webhooks

Webhooks are configured within the App (no code required) and send HTTP requests to an external service when a specific event is triggered.

The Webhook Object

id integer
Primary key of the webhook.

name string
Name for the webhook. Shown in the Admin App.

method string
HTTP method to use. One of GET, POST.

url string
Where to send the request too.

status string
Status of the webhook. One of active, inactive.

data boolean
Whether or not to send the event data to the external endpoint.

actions csv
When to fire the webhook. Can contain create, update, delete.

collections csv
What collections to fire this webhook on.

{
	"data": {
		"id": 1,
		"name": "Build Website",
		"method": "POST",
		"url": "https://example.com/",
		"status": "active",
		"data": true,
		"actions": ["create", "update"],
		"collections": ["articles"]
	}
}

List Webhooks

List all webhooks that exist in Directus.

Request

GET /webhooks

SEARCH /webhooks

POST /graphql/system

type Query {
	webhooks: [directus_webhooks]
}

import { createDirectus } from '@directus/sdk';
import { rest, readWebhooks } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	readWebhooks({
		fields: ['*'],
	})
);

Learn more about SEARCH ->

Query Parameters

Supports all global query parameters.

Response

An array of up to limit webhook objects. If no items are available, data will be an empty array.

Example

GET /webhooks

SEARCH /webhooks

POST /graphql/system

query {
	webhooks {
		url
		method
	}
}

import { createDirectus } from '@directus/sdk';
import { rest, readWebhooks } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	readWebhooks({
		fields: ['*'],
	})
);

Retrieve a Webhook

List an existing webhook by primary key.

Request

GET /webhooks/:id

POST /graphql/system

type Query {
	webhooks_by_id(id: ID!): directus_webhooks
}

import { createDirectus } from '@directus/sdk';
import { rest, readWebhook } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	readWebhook('webhook_id', {
		fields: ['*'],
	})
);

Query Parameters

Supports all global query parameters.

Returns

Returns the requested webhook object.

Examples

GET /webhooks/15

POST /graphql/system

query {
	webhooks_by_id(id: 15) {
		url
		actions
		method
	}
}

import { createDirectus } from '@directus/sdk';
import { rest, readWebhook } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	readWebhook('2', {
		fields: ['*'],
	})
);

Create a Webhook

Create a new webhook.

Request

POST /webhooks

{
	"name": "name",
	"actions": ["webhook_action_1", "webhook_action_2"],
	"collections": ["collection to act on"],
	"url": "url of webhook"
}

POST /graphql/system

type Mutation {
	create_webhooks_item(data: create_directus_webhooks_input!): directus_webhooks
}

import { createDirectus } from '@directus/sdk';
import { rest, createWebhook } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	createWebhook({
		name: 'webhook_name',
		collections: 'collection_name',
		actions: ['action_1', 'action_2', 'action_3'],
		url: 'webhook_url',
	})
);

Query Parameters

Supports all global query parameters.

Request Body

A partial webhook object.

name, actions, collections, and url are required.

Response

Returns the webhook object for the created webhook.

Example

POST /webhooks

{
	"name": "Example",
	"actions": ["create", "update"],
	"collections": ["articles"],
	"url": "https://example.com"
}

POST /graphql/system

mutation {
	create_webhooks_item(
		data: { name: "Example", actions: ["create", "update"], collections: ["articles"], url: "https://example.com" }
	) {
		id
		name
	}
}

import { createDirectus } from '@directus/sdk';
import { rest, createWebhook } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	createWebhook({
		name: 'Articles Activity',
		method: 'POST',
		collections: 'articles',
		actions: ['create', 'update', 'delete'],
		url: 'https://directus.example.com/articles_activity',
	})
);

Create Multiple Webhook

Create multiple new webhooks.

Request

POST /webhooks

[
	{
		"name": "name_1",
		"actions": ["webhook_action_1", "webhook_action_2"],
		"collections": ["collection to act on"],
		"url": "url of webhook_1"
	},
	{
		"name": "name_2",
		"actions": ["webhook_action_1", "webhook_action_2"],
		"collections": ["collection to act on"],
		"url": "url of webhook_2"
	}
]

POST /graphql/system

type Mutation {
	create_webhooks_items(data: [create_directus_webhooks_input!]!): [directus_webhooks]
}

import { createDirectus } from '@directus/sdk';
import { rest, createWebhooks } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	createWebhooks([
		{
			name: 'name_1',
			collections: ['collection to act on'],
			actions: ['webhook_action_1', 'webhook_action_2'],
			url: 'url of webhook_1',
		},
		{
			name: 'webhook_2_name',
			actions: ['action_1', 'action_2', 'action_3'],
			collections: 'collection_2_name',
			url: 'webhook_2_url',
		},
	])
);

Query Parameters

Supports all global query parameters.

Request Body

An array of partial webhook object.

name, actions, collections, and url are required.

Response

Returns the webhook objects for the created webhooks.

Example

POST /webhooks

[
	{
		"name": "Example",
		"actions": ["create", "update"],
		"collections": ["articles"],
		"url": "https://example.com"
	},
	{
		"name": "Second Example",
		"actions": ["delete"],
		"collections": ["articles"],
		"url": "https://example.com/on-delete"
	}
]

POST /graphql/system

mutation {
	create_webhooks_items(
		data: [
			{ name: "Example", actions: ["create", "update"], collections: ["articles"], url: "https://example.com" }
			{ name: "Second Example", actions: ["delete"], collections: ["articles"], url: "https://example.com/on-delete" }
		]
	) {
		id
		name
	}
}

import { createDirectus } from '@directus/sdk';
import { rest, createWebhooks } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	createWebhooks([
		{
			name: 'Articles Activity',
			method: 'POST',
			collections: 'articles',
			actions: ['create', 'update', 'delete'],
			url: 'https://directus.example.com/articles_activity',
		},
		{
			name: 'Author Changes',
			method: 'POST',
			collections: 'authors',
			actions: ['update'],
			url: 'https://directus.example.com/authors_changes',
		},
	])
);

Update a Webhook

Update an existing webhook.

Request

PATCH /webhooks/:id

{
	"webhook_field": "value"
}

POST /graphql/system

type Mutation {
	update_webhooks_item(id: ID!, data: update_directus_webhooks_input!): directus_webhooks
}

import { createDirectus } from '@directus/sdk';
import { rest, updateWebhook } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	updateWebhook('webhook_id', {
		field: 'value',
	})
);

Query Parameters

Supports all global query parameters.

Request Body

A partial webhook object.

Response

Returns the webhook object for the updated webhook.

Example

PATCH /webhooks/15

{
	"name": "Build Website"
}

POST /graphql/system

mutation {
	update_webhooks_item(id: 15, data: { name: "Build Website" }) {
		name
	}
}

import { createDirectus } from '@directus/sdk';
import { rest, updateWebhook } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	updateWebhook('6', {
		actions: ['update', 'delete'],
	})
);

Update Multiple Webhooks

Update multiple existing webhooks.

Request

PATCH /webhooks

{
	"keys": ["webhook_1_key", "webhook_2_key"],
	"data": {
		"webhook_object_field": "value_1"
	}
}

POST /graphql/system

type Mutation {
	update_webhooks_items(ids: [ID!]!, data: update_directus_webhooks_input!): [directus_webhooks]
}

import { createDirectus } from '@directus/sdk';
import { rest, updateWebhooks } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	updateWebhooks(['webhook_1_id', 'webhook_2_id'], {
		webhook_field: 'value',
	})
);

Query Parameters

Supports all global query parameters.

Request Body

keys Required
Array of primary keys of the webhooks you'd like to update.

data Required
Any of the webhook object's properties.

Response

Returns the webhook objects for the updated webhooks.

REST API

Example

PATCH /webhooks

{
	"keys": [15, 41],
	"data": {
		"name": "Build Website"
	}
}

POST /graphql/system

mutation {
	update_webhooks_items(ids: [15, 41], data: { name: "Build Website" }) {
		name
	}
}

import { createDirectus } from '@directus/sdk';
import { rest, updateWebhooks } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	updateWebhooks(['5', '6'], {
		status: 'inactive',
	})
);

Delete a Webhook

Delete an existing webhook.

Request

DELETE /webhooks/:id

POST /graphql/system

type Mutation {
	delete_webhooks_item(id: ID!): delete_one
}

import { createDirectus } from '@directus/sdk';
import { rest, deleteWebhook } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(deleteWebhook('webhook_id'));

Response

Empty body.

Example

DELETE /webhooks/15

POST /graphql/system

mutation {
	delete_webhooks_item(id: 15) {
		id
	}
}

import { createDirectus } from '@directus/sdk';
import { rest, deleteWebhook } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(deleteWebhook('1'));

Delete Multiple Webhooks

Delete multiple existing webhooks.

Request

DELETE /webhooks

["webhook_1_key", "webhook_2_key", "webhook_3_key"]

POST /graphql/system

type Mutation {
	delete_webhooks_items(ids: [ID!]!): delete_many
}

import { createDirectus } from '@directus/sdk';
import { rest, deleteWebhooks } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(deleteWebhooks(['webhook_1_id', 'webhook_2_id']));

Request Body

An array of webhook primary keys

Response

Empty body.

Example

DELETE /webhooks

[2, 15, 41]

POST /graphql/system

mutation {
	delete_webhooks_items(ids: [2, 15, 41]) {
		ids
	}
}

import { createDirectus } from '@directus/sdk';
import { rest, deleteWebhooks } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(deleteWebhooks(['2', '3']));