Webhook Listeners — Nextcloud latest Administration Manual latest documentation

# Webhook Listeners

Nextcloud supports listening to internal events via webhooks.

## Installation

> - Enable the `webhook_listeners` app that comes bundled with Nextcloud

    occ app:enable webhook_listeners

## Listening to events

You can use the OCS API to add webhooks for specific events: https://docs.nextcloud.com/server/latest/developer_manual/_static/openapi.html#/operations/webhook_listeners-webhooks-index

Note: When authenticating with the OCS API to register webhooks the account you authenticate as must have administrator rights or delegated administrator rights.

### Filters

When registering a webhook listener, you can specify a filter parameter. The value of this parameter must be a JSON object whose properties represent filter conditions. The `{}` is an empty query, meaning no specific criteria, so all events are matched.

If you would like to match events fired by a specific user, you can pass `{ "user.uid": "bob" }` to match all events fired in the context of user `"bob"`.

If you would like to enforce multiple criteria, you can simply pass multiple properties `{ "event.tableId": 42, "event.rowId": 3 }`

You can also use additional comparison operators (`$eq, $ne, $gt, $gte, $lt, $lte, $in, $nin`) as well as logical operators (`$and, $or, $not, $nor`). For example use `{ "time" : { "$lt": 1711971024 } }` to accept only events prior to April 1st 2024 and `{ "time" : { "$not": { "$lt": 1711971024 } } }` to accept events after April 1st 2024.

### Speeding up webhook dispatch

This app uses background jobs to trigger the registered webhooks. Thus, by default, webhooks will be triggered only every 5 minutes, as the default cron interval is 5 minutes. To trigger webhooks earlier, you can set up a background job worker. The following command will launch a worker for the webhook call background job:

    occ background-job:worker "OCA\\WebhookListeners\\BackgroundJobs\\WebhookCall"

It is recommended to restart this worker once a day to make sure code changes are effective and avoid memory leaks, for example by registering it as a systemd service with a daily timer.

## Nextcloud Webhook Events

This is an exhaustive list of available events. It features the event ID and the available variables for filtering.

> - OCA\Forms\Events\FormSubmittedEvent

> >     array{
> >       "user": array {"uid": string, "displayName": string},
> >       "time": int,
> >       "event": array{
> >         "class": string,
> >         "form": array{
> >          "id": int,
> >          "hash": string,
> >          "title": string,
> >          "description": string,
> >          "ownerId": string,
> >          "fileId": string|null,
> >          "fileFormat": string|null,
> >          "created": int,
> >          "access": int,
> >          "expires": int,
> >          "isAnonymous": bool,
> >          "submitMultiple": bool,
> >          "showExpiration": bool,
> >          "lastUpdated": int,
> >          "submissionMessage": string|null,
> >          "state": int,
> >         },
> >         "submission": array{
> >           "id": int,
> >           "formId": int,
> >           "userId": string,
> >           "timestamp": int,
> >         },
> >       }
> >     }

> - OCA\Tables\Event\RowAddedEvent

> >     array{
> >       "user": array {"uid": string, "displayName": string},
> >       "time": int,
> >       "event": array{
> >         "class": string,
> >         "tableId": int,
> >         "rowId": int,
> >         "previousValues": null|array<int, mixed>,
> >         "values": null|array<int, mixed>
> >       }
> >     }

> - OCA\Tables\Event\RowDeletedEvent

> >     array{
> >       "user": array {"uid": string, "displayName": string},
> >       "time": int,
> >       "event": array{
> >         "class": string,
> >         "tableId": int,
> >         "rowId": int,
> >         "previousValues": null|array<int, mixed>,
> >         "values": null|array<int, mixed>
> >       }
> >     }

> - OCA\Tables\Event\RowUpdatedEvent

> >     array{
> >       "user": array {"uid": string, "displayName": string},
> >       "time": int,
> >       "event": array{
> >         "class": string,
> >         "tableId": int,
> >         "rowId": int,
> >         "previousValues": null|array<int, mixed>,
> >         "values": null|array<int, mixed>
> >       }
> >     }

> - OCP\Files\Events\Node\BeforeNodeCreatedEvent

> >     array{
> >       "user": array {"uid": string, "displayName": string},
> >       "time": int,
> >       "event": array{
> >         "class": string,
> >         "node": array{"id": string, "path": string}
> >       }
> >     }

> - OCP\Files\Events\Node\BeforeNodeTouchedEvent

> >     array{
> >       "user": array {"uid": string, "displayName": string},
> >       "time": int,
> >       "event": array{
> >         "class": string,
> >         "node": array{"id": string, "path": string}
> >       }
> >     }

> - OCP\Files\Events\Node\BeforeNodeWrittenEvent

> >     array{
> >       "user": array {"uid": string, "displayName": string},
> >       "time": int,
> >       "event": array{
> >         "class": string,
> >         "node": array{"id": string, "path": string}
> >       }
> >     }

> - OCP\Files\Events\Node\BeforeNodeReadEvent

> >     array{
> >       "user": array {"uid": string, "displayName": string},
> >       "time": int,
> >       "event": array{
> >         "class": string,
> >         "node": array{"id": string, "path": string}
> >       }
> >     }

> - OCP\Files\Events\Node\BeforeNodeDeletedEvent

> >     array{
> >       "user": array {"uid": string, "displayName": string},
> >       "time": int,
> >       "event": array{
> >         "class": string,
> >         "node": array{"id": string, "path": string}
> >       }
> >     }

> - OCP\Files\Events\Node\NodeCreatedEvent

> >     array{
> >       "user": array {"uid": string, "displayName": string},
> >       "time": int,
> >       "event": array{
> >         "class": string,
> >         "node": array{"id": string, "path": string}
> >       }
> >     }

> - OCP\Files\Events\Node\NodeTouchedEvent

> >     array{
> >       "user": array {"uid": string, "displayName": string},
> >       "time": int,
> >       "event": array{
> >         "class": string,
> >         "node": array{"id": string, "path": string}
> >       }
> >     }

> - OCP\Files\Events\Node\NodeWrittenEvent

> >     array{
> >       "user": array {"uid": string, "displayName": string},
> >       "time": int,
> >       "event": array{
> >         "class": string,
> >         "node": array{"id": string, "path": string}
> >       }
> >     }

> - OCP\Files\Events\Node\NodeReadEvent

> >     array{
> >       "user": array {"uid": string, "displayName": string},
> >       "time": int,
> >       "event": array{
> >         "class": string,
> >         "node": array{"id": string, "path": string}
> >       }
> >     }

> - OCP\Files\Events\Node\NodeDeletedEvent

> >     array{
> >       "user": array {"uid": string, "displayName": string},
> >       "time": int,
> >       "event": array{
> >         "class": string,
> >         "node": array{"id": string, "path": string}
> >       }
> >     }

> - OCP\Files\Events\Node\NodeCopiedEvent

> >     array{
> >       "user": array {"uid": string, "displayName": string},
> >       "time": int,
> >       "event": array{
> >         "class": string,
> >         "source": array{"id": string, "path": string}
> >         "target": array{"id": string, "path": string}
> >       }
> >     }

> - OCP\Files\Events\Node\NodeRestoredEvent

> >     array{
> >       "user": array {"uid": string, "displayName": string},
> >       "time": int,
> >       "event": array{
> >         "class": string,
> >         "source": array{"id": string, "path": string}
> >         "target": array{"id": string, "path": string}
> >       }
> >     }

> - OCP\Files\Events\Node\NodeRenamedEvent

> >     array{
> >       "user": array {"uid": string, "displayName": string},
> >       "time": int,
> >       "event": array{
> >         "class": string,
> >         "source": array{"id": string, "path": string}
> >         "target": array{"id": string, "path": string}
> >       }
> >     }

> - OCP\Files\Events\Node\BeforeNodeCopiedEvent

> >     array{
> >       "user": array {"uid": string, "displayName": string},
> >       "time": int,
> >       "event": array{
> >         "class": string,
> >         "source": array{"id": string, "path": string}
> >         "target": array{"id": string, "path": string}
> >       }
> >     }

> - OCP\Files\Events\Node\BeforeNodeRestoredEvent

> >     array{
> >       "user": array {"uid": string, "displayName": string},
> >       "time": int,
> >       "event": array{
> >         "class": string,
> >         "source": array{"id": string, "path": string}
> >         "target": array{"id": string, "path": string}
> >       }
> >     }

> - OCP\Files\Events\Node\BeforeNodeRenamedEvent

> >     array{
> >       "user": array {"uid": string, "displayName": string},
> >       "time": int,
> >       "event": array{
> >         "class": string,
> >         "source": array{"id": string, "path": string}
> >         "target": array{"id": string, "path": string}
> >       }
> >     }

Read the Docs v: latest

Versions
  28
  29
  stable
  latest

Downloads

On Read the Docs
  Project Home
  Builds