API reference

Webhooks

Subscribe a project to lifecycle events. Verify delivery signatures and deduplicate event IDs in your receiver.

How it fits together

01Subscribe a destination to a project's events. Returns the signing secret once
02Queue a finished delivery to be attempted again. The attempt history is preserved
03Issue a new signing secret, keeping the old one for a bounded overlap. Returns it once

Select an action to see its complete inputs, request, response, and status codes.

Subscribe a destination to a project's events. Returns the signing secret once

POST/api/v1/chat/projects/{project_id}/webhooks

Production base URLhttps://api.mahvashai.ir

AuthenticationUser access JWT

ResponseMahvash product envelope

Content typeapplication/json

Parameters

The table shows the accepted inputs for this endpoint. Examples use placeholders and illustrate a safe integration pattern.

Name	Location	Type	Required	Support	Details
`project_id`	Path	string	Required	Mahvash extension	Project ID.
`X-Request-ID`	Header	string	Optional	Mahvash extension	Client-supplied correlation ID. Echoed on every response; replaced when absent or malformed.
`X-Mahvash-Project`	Header	string	Optional	Mahvash extension	Project slug or ID within the caller's organization. Narrows the request principal; it can never widen it.
`event_types`	Body	array<value>	Required	Mahvash extension	Event types to receive. An unknown type is refused, never dropped.
`url`	Body	string	Required	Mahvash extension	HTTPS destination. Validated against network policy here and again before every delivery.

Request

curl -X POST 'https://api.mahvashai.ir/api/v1/chat/projects/<project_id>/webhooks' \
  -H "Authorization: Bearer $MAHVASH_USER_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "event_types": [
    "response.completed"
  ],
  "url": "https://hooks.example.com/mahvash"
}'

Response

{
  "status": 0,
  "data": "<value>"
}

Illustrative response shape; actual fields depend on the operation and model.

Status codes

HTTP	Details
201	Subscribe a destination to a project's events. Returns the signing secret once.
400	The request is not valid.
401	Authentication credentials are missing or invalid.
403	The principal is not allowed to perform this request.
404	No such resource is visible to this principal.
429	A quota or rate limit was exceeded.
500	An internal error occurred.

Queue a finished delivery to be attempted again. The attempt history is preserved

POST/api/v1/chat/webhook-deliveries/{delivery_id}/replay

Production base URLhttps://api.mahvashai.ir

AuthenticationUser access JWT

ResponseMahvash product envelope

Parameters

The table shows the accepted inputs for this endpoint. Examples use placeholders and illustrate a safe integration pattern.

Name	Location	Type	Required	Support	Details
`delivery_id`	Path	string	Required	Mahvash extension	Delivery ID.
`X-Request-ID`	Header	string	Optional	Mahvash extension	Client-supplied correlation ID. Echoed on every response; replaced when absent or malformed.
`X-Mahvash-Project`	Header	string	Optional	Mahvash extension	Project slug or ID within the caller's organization. Narrows the request principal; it can never widen it.

Request

curl -X POST 'https://api.mahvashai.ir/api/v1/chat/webhook-deliveries/<delivery_id>/replay' \
  -H "Authorization: Bearer $MAHVASH_USER_JWT"

Response

{
  "status": 0,
  "data": "<value>"
}

Illustrative response shape; actual fields depend on the operation and model.

Status codes

HTTP	Details
200	Queue a finished delivery to be attempted again. The attempt history is preserved.
400	The request is not valid.
401	Authentication credentials are missing or invalid.
403	The principal is not allowed to perform this request.
404	No such resource is visible to this principal.
429	A quota or rate limit was exceeded.
500	An internal error occurred.

Issue a new signing secret, keeping the old one for a bounded overlap. Returns it once

POST/api/v1/chat/webhooks/{endpoint_id}/rotate

Production base URLhttps://api.mahvashai.ir

AuthenticationUser access JWT

ResponseMahvash product envelope

Parameters

The table shows the accepted inputs for this endpoint. Examples use placeholders and illustrate a safe integration pattern.

Name	Location	Type	Required	Support	Details
`endpoint_id`	Path	string	Required	Mahvash extension	Webhook subscription ID.
`X-Request-ID`	Header	string	Optional	Mahvash extension	Client-supplied correlation ID. Echoed on every response; replaced when absent or malformed.
`X-Mahvash-Project`	Header	string	Optional	Mahvash extension	Project slug or ID within the caller's organization. Narrows the request principal; it can never widen it.

Request

curl -X POST 'https://api.mahvashai.ir/api/v1/chat/webhooks/<endpoint_id>/rotate' \
  -H "Authorization: Bearer $MAHVASH_USER_JWT"

Response

{
  "status": 0,
  "data": "<value>"
}

Illustrative response shape; actual fields depend on the operation and model.

Status codes

HTTP	Details
201	Issue a new signing secret, keeping the old one for a bounded overlap. Returns it once.
401	Authentication credentials are missing or invalid.
403	The principal is not allowed to perform this request.
404	No such resource is visible to this principal.
429	A quota or rate limit was exceeded.
500	An internal error occurred.

One webhook subscription and its delivery health

GET/api/v1/chat/webhooks/{endpoint_id}

Production base URLhttps://api.mahvashai.ir

AuthenticationUser access JWT

ResponseMahvash product envelope

Parameters

The table shows the accepted inputs for this endpoint. Examples use placeholders and illustrate a safe integration pattern.

Name	Location	Type	Required	Support	Details
`endpoint_id`	Path	string	Required	Mahvash extension	Webhook subscription ID.
`X-Request-ID`	Header	string	Optional	Mahvash extension	Client-supplied correlation ID. Echoed on every response; replaced when absent or malformed.
`X-Mahvash-Project`	Header	string	Optional	Mahvash extension	Project slug or ID within the caller's organization. Narrows the request principal; it can never widen it.

Request

curl -X GET 'https://api.mahvashai.ir/api/v1/chat/webhooks/<endpoint_id>' \
  -H "Authorization: Bearer $MAHVASH_USER_JWT"

Response

{
  "status": 0,
  "data": "<value>"
}

Illustrative response shape; actual fields depend on the operation and model.

Status codes

HTTP	Details
200	One webhook subscription and its delivery health.
401	Authentication credentials are missing or invalid.
403	The principal is not allowed to perform this request.
404	No such resource is visible to this principal.
429	A quota or rate limit was exceeded.
500	An internal error occurred.

Retune which events a subscription receives, or enable and disable it. The URL is immutable

PATCH/api/v1/chat/webhooks/{endpoint_id}

Production base URLhttps://api.mahvashai.ir

AuthenticationUser access JWT

ResponseMahvash product envelope

Content typeapplication/json

Parameters

The table shows the accepted inputs for this endpoint. Examples use placeholders and illustrate a safe integration pattern.

Name	Location	Type	Required	Support	Details
`endpoint_id`	Path	string	Required	Mahvash extension	Webhook subscription ID.
`X-Request-ID`	Header	string	Optional	Mahvash extension	Client-supplied correlation ID. Echoed on every response; replaced when absent or malformed.
`X-Mahvash-Project`	Header	string	Optional	Mahvash extension	Project slug or ID within the caller's organization. Narrows the request principal; it can never widen it.
`event_types`	Body	array<value>	Optional	Mahvash extension	Replacement list of event types.
`status`	Body	string	Optional	Mahvash extension	ACTIVE or DISABLED. Re-enabling clears the automatic-disablement failure count.

Request

curl -X PATCH 'https://api.mahvashai.ir/api/v1/chat/webhooks/<endpoint_id>' \
  -H "Authorization: Bearer $MAHVASH_USER_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "event_types": [
    "response.failed"
  ]
}'

Response

{
  "status": 0,
  "data": "<value>"
}

Illustrative response shape; actual fields depend on the operation and model.

Status codes

HTTP	Details
200	Retune which events a subscription receives, or enable and disable it. The URL is immutable.
400	The request is not valid.
401	Authentication credentials are missing or invalid.
403	The principal is not allowed to perform this request.
404	No such resource is visible to this principal.
429	A quota or rate limit was exceeded.
500	An internal error occurred.

Remove a webhook subscription and everything queued for it

DELETE/api/v1/chat/webhooks/{endpoint_id}

Production base URLhttps://api.mahvashai.ir

AuthenticationUser access JWT

ResponseMahvash product envelope

Parameters

The table shows the accepted inputs for this endpoint. Examples use placeholders and illustrate a safe integration pattern.

Name	Location	Type	Required	Support	Details
`endpoint_id`	Path	string	Required	Mahvash extension	Webhook subscription ID.
`X-Request-ID`	Header	string	Optional	Mahvash extension	Client-supplied correlation ID. Echoed on every response; replaced when absent or malformed.
`X-Mahvash-Project`	Header	string	Optional	Mahvash extension	Project slug or ID within the caller's organization. Narrows the request principal; it can never widen it.

Request

curl -X DELETE 'https://api.mahvashai.ir/api/v1/chat/webhooks/<endpoint_id>' \
  -H "Authorization: Bearer $MAHVASH_USER_JWT"

Response

This endpoint returns no JSON body or delivers binary content.

Status codes

HTTP	Details
204	Remove a webhook subscription and everything queued for it.
401	Authentication credentials are missing or invalid.
403	The principal is not allowed to perform this request.
404	No such resource is visible to this principal.
429	A quota or rate limit was exceeded.
500	An internal error occurred.

List a project's webhook subscriptions. Never includes the signing secret

GET/api/v1/chat/projects/{project_id}/webhooks

Production base URLhttps://api.mahvashai.ir

AuthenticationUser access JWT

ResponseMahvash product envelope

Parameters

The table shows the accepted inputs for this endpoint. Examples use placeholders and illustrate a safe integration pattern.

Name	Location	Type	Required	Support	Details
`project_id`	Path	string	Required	Mahvash extension	Project ID.
`search`	Query	string	Optional	Mahvash extension	Case-insensitive search over endpoint URL and disabled reason.
`status`	Query	string	Optional	Mahvash extension	Filter by ACTIVE or DISABLED.
`page`	Query	integer	Optional	Mahvash extension	One-based page number when bounded pagination is requested.
`page_size`	Query	integer	Optional	Mahvash extension	Page size from 1 through 100 when bounded pagination is requested.
`X-Request-ID`	Header	string	Optional	Mahvash extension	Client-supplied correlation ID. Echoed on every response; replaced when absent or malformed.
`X-Mahvash-Project`	Header	string	Optional	Mahvash extension	Project slug or ID within the caller's organization. Narrows the request principal; it can never widen it.

Request

curl -X GET 'https://api.mahvashai.ir/api/v1/chat/projects/<project_id>/webhooks' \
  -H "Authorization: Bearer $MAHVASH_USER_JWT"

Response

{
  "status": 0,
  "data": "<value>"
}

Illustrative response shape; actual fields depend on the operation and model.

Status codes

HTTP	Details
200	List a project's webhook subscriptions. Never includes the signing secret.
401	Authentication credentials are missing or invalid.
403	The principal is not allowed to perform this request.
404	No such resource is visible to this principal.
429	A quota or rate limit was exceeded.
500	An internal error occurred.

Recent delivery attempts. The receiver's response body is never stored

GET/api/v1/chat/webhooks/{endpoint_id}/deliveries

Production base URLhttps://api.mahvashai.ir

AuthenticationUser access JWT

ResponseMahvash product envelope

Parameters

The table shows the accepted inputs for this endpoint. Examples use placeholders and illustrate a safe integration pattern.

Name	Location	Type	Required	Support	Details
`endpoint_id`	Path	string	Required	Mahvash extension	Webhook subscription ID.
`search`	Query	string	Optional	Mahvash extension	Case-insensitive search over event ID, event type, and last error code.
`status`	Query	string	Optional	Mahvash extension	Filter by delivery lifecycle status.
`page`	Query	integer	Optional	Mahvash extension	One-based page number when bounded pagination is requested.
`page_size`	Query	integer	Optional	Mahvash extension	Page size from 1 through 100 when bounded pagination is requested.
`X-Request-ID`	Header	string	Optional	Mahvash extension	Client-supplied correlation ID. Echoed on every response; replaced when absent or malformed.
`X-Mahvash-Project`	Header	string	Optional	Mahvash extension	Project slug or ID within the caller's organization. Narrows the request principal; it can never widen it.

Request

curl -X GET 'https://api.mahvashai.ir/api/v1/chat/webhooks/<endpoint_id>/deliveries' \
  -H "Authorization: Bearer $MAHVASH_USER_JWT"

Response

{
  "status": 0,
  "data": "<value>"
}

Illustrative response shape; actual fields depend on the operation and model.

Status codes

HTTP	Details
200	Recent delivery attempts. The receiver's response body is never stored.
401	Authentication credentials are missing or invalid.
403	The principal is not allowed to perform this request.
404	No such resource is visible to this principal.
429	A quota or rate limit was exceeded.
500	An internal error occurred.

The closed set of events a subscription may listen for

GET/api/v1/chat/webhooks/event-types

Production base URLhttps://api.mahvashai.ir

AuthenticationUser access JWT

ResponseMahvash product envelope

Parameters

The table shows the accepted inputs for this endpoint. Examples use placeholders and illustrate a safe integration pattern.

Name	Location	Type	Required	Support	Details
`X-Request-ID`	Header	string	Optional	Mahvash extension	Client-supplied correlation ID. Echoed on every response; replaced when absent or malformed.
`X-Mahvash-Project`	Header	string	Optional	Mahvash extension	Project slug or ID within the caller's organization. Narrows the request principal; it can never widen it.

Request

curl -X GET 'https://api.mahvashai.ir/api/v1/chat/webhooks/event-types' \
  -H "Authorization: Bearer $MAHVASH_USER_JWT"

Response

{
  "status": 0,
  "data": "<value>"
}

Illustrative response shape; actual fields depend on the operation and model.

Status codes

HTTP	Details
200	The closed set of events a subscription may listen for.
401	Authentication credentials are missing or invalid.
429	A quota or rate limit was exceeded.
500	An internal error occurred.