API Reference: Webhooks

Outbound webhooks notify your own systems when events happen inside ProcessMind. Every delivery is a JSON POST signed with your webhook secret: the X-ProcessMind-Signature header contains sha256=<hex>, an HMAC-SHA256 of the raw request body. Verify the signature against the exact bytes you received (before parsing the JSON) and reject deliveries whose signature does not match. Each body also carries a deliveryId you can use to deduplicate at-least-once deliveries.

List outbound webhooks

Endpoint: GET /v1/tenant/{tenantId}/webhooks

Auth: Tenant-scoped API key · read scope

Parameters:

Name	Type	Location	Required	Description
tenantId	string	path	Yes	Format: uuid
limit	integer	query	No	Maximum number of items to return
offset	integer	query	No	Number of items to skip

Response (200):

List of webhooks

[
	{
		"id": "00000000-0000-0000-0000-000000000000",
		"url": "string",
		"events": [
			"process.created"
		],
		"description": "string",
		"isActive": true,
		"createdAt": "2024-03-15T16:30:00Z"
	}
]

Errors:

• 401 Missing, invalid, disabled or expired API key

Create an outbound webhook (returns the signing secret once)

Endpoint: POST /v1/tenant/{tenantId}/webhooks

Auth: Tenant-scoped API key · write scope

Parameters:

Name	Type	Location	Required	Description
tenantId	string	path	Yes	Format: uuid

Request Body:

{
	"url": "string",
	"events": [
		"process.created"
	],
	"description": "string"
}

Field	Type	Required	Description
url	string	Yes	Public https endpoint that receives signed POST deliveries (no private/loopback addresses)
events	process.created | process.updated | process.deleted | mapping.created | data.ready | simulation.completed | webhook.test[]	Yes	Events that trigger a delivery to this webhook
description	string	No	Optional description Max length: 500

Response (201):

Created webhook (includes the signing secret)

{
	"id": "00000000-0000-0000-0000-000000000000",
	"url": "string",
	"events": [
		"process.created"
	],
	"description": "string",
	"isActive": true,
	"createdAt": "2024-03-15T16:30:00Z",
	"secret": "string"
}

Field	Type	Required	Description
id	string	Yes	Format: uuid
url	string	Yes	Format: uri
events	process.created | process.updated | process.deleted | mapping.created | data.ready | simulation.completed | webhook.test[]	Yes
description	string	Yes	Max length: 500
isActive	boolean	Yes	Default: true
createdAt	string	Yes	Format: date-time
secret	string	Yes	Signing secret; only returned here, at creation

Errors:

• 400 Bad request: e.g. an invalid filter expression, a process without a model, an unsupported upload type or a missing required field
• 401 Missing, invalid, disabled or expired API key

Get a single outbound webhook

Endpoint: GET /v1/tenant/{tenantId}/webhooks/{webhookId}

Auth: Tenant-scoped API key · read scope

Parameters:

Name	Type	Location	Required	Description
tenantId	string	path	Yes	Format: uuid
webhookId	string	path	Yes	Format: uuid

Response (200):

Webhook

{
	"id": "00000000-0000-0000-0000-000000000000",
	"url": "string",
	"events": [
		"process.created"
	],
	"description": "string",
	"isActive": true,
	"createdAt": "2024-03-15T16:30:00Z"
}

Field	Type	Required	Description
id	string	Yes	Format: uuid
url	string	Yes	Format: uri
events	process.created | process.updated | process.deleted | mapping.created | data.ready | simulation.completed | webhook.test[]	Yes
description	string	Yes	Max length: 500
isActive	boolean	Yes	Default: true
createdAt	string	Yes	Format: date-time

Errors:

• 401 Missing, invalid, disabled or expired API key
• 404 Resource not found

Update an outbound webhook

Endpoint: PUT /v1/tenant/{tenantId}/webhooks/{webhookId}

Auth: Tenant-scoped API key · write scope

Parameters:

Name	Type	Location	Required	Description
tenantId	string	path	Yes	Format: uuid
webhookId	string	path	Yes	Format: uuid

Request Body:

{
	"url": "string",
	"events": [
		"process.created"
	],
	"description": "string",
	"isActive": true
}

Field	Type	Required	Description
url	string	No	Public https endpoint that receives signed POST deliveries
events	process.created | process.updated | process.deleted | mapping.created | data.ready | simulation.completed | webhook.test[]	No	Events that trigger a delivery to this webhook
description	string	No	Optional description Max length: 500
isActive	boolean	No	Whether the webhook is enabled

Response (200):

Updated webhook

{
	"id": "00000000-0000-0000-0000-000000000000",
	"url": "string",
	"events": [
		"process.created"
	],
	"description": "string",
	"isActive": true,
	"createdAt": "2024-03-15T16:30:00Z"
}

Field	Type	Required	Description
id	string	Yes	Format: uuid
url	string	Yes	Format: uri
events	process.created | process.updated | process.deleted | mapping.created | data.ready | simulation.completed | webhook.test[]	Yes
description	string	Yes	Max length: 500
isActive	boolean	Yes	Default: true
createdAt	string	Yes	Format: date-time

Errors:

• 401 Missing, invalid, disabled or expired API key
• 404 Resource not found

Delete an outbound webhook

Endpoint: DELETE /v1/tenant/{tenantId}/webhooks/{webhookId}

Auth: Tenant-scoped API key · write scope

Parameters:

Name	Type	Location	Required	Description
tenantId	string	path	Yes	Format: uuid
webhookId	string	path	Yes	Format: uuid

Response (200):

Webhook deleted

{
	"deleted": true
}

Field	Type	Required	Description
deleted	boolean	Yes

Errors:

• 401 Missing, invalid, disabled or expired API key
• 404 Resource not found

Trigger a test delivery to the webhook

Endpoint: POST /v1/tenant/{tenantId}/webhooks/{webhookId}/test

Auth: Tenant-scoped API key · write scope

Parameters:

Name	Type	Location	Required	Description
tenantId	string	path	Yes	Format: uuid
webhookId	string	path	Yes	Format: uuid

Response (200):

Test delivery triggered

{
	"message": "string"
}

Field	Type	Required	Description
message	string	Yes

Errors:

• 401 Missing, invalid, disabled or expired API key
• 404 Resource not found