.. _`rest-webhooks`:

Webhooks
========

.. note:: This page is about how to modify webhook settings themselves through the REST API. If you just want to know
          how webhooks work, go here: :ref:`webhooks`

Resource description
--------------------

The webhook resource contains the following public fields:

.. rst-class:: rest-resource-table

===================================== ========================== =======================================================
Field                                 Type                       Description
===================================== ========================== =======================================================
id                                    integer                    Internal ID of the webhook
enabled                               boolean                    If ``false``, this webhook will not receive any notifications
target_url                            string                     The URL to call
all_events                            boolean                    If ``true``, this webhook will receive notifications
                                                                 on all events of this organizer
limit_events                          list of strings            If ``all_events`` is ``false``, this is a list of
                                                                 event slugs this webhook is active for
action_types                          list of strings            A list of action type filters that limit the
                                                                 notifications sent to this webhook. See below for
                                                                 valid values
comment                               string                     Internal comment on this webhook, default ``null``
===================================== ========================== =======================================================

The following values for ``action_types`` are valid with pretix core:

    * ``pretix.event.order.placed``
    * ``pretix.event.order.placed.require_approval``
    * ``pretix.event.order.paid``
    * ``pretix.event.order.canceled``
    * ``pretix.event.order.reactivated``
    * ``pretix.event.order.expired``
    * ``pretix.event.order.expirychanged``
    * ``pretix.event.order.modified``
    * ``pretix.event.order.contact.changed``
    * ``pretix.event.order.changed.*``
    * ``pretix.event.order.deleted`` (can only occur for test mode orders)
    * ``pretix.event.order.refund.created``
    * ``pretix.event.order.refund.created.externally``
    * ``pretix.event.order.refund.requested``
    * ``pretix.event.order.refund.done``
    * ``pretix.event.order.refund.canceled``
    * ``pretix.event.order.refund.failed``
    * ``pretix.event.order.payment.confirmed``
    * ``pretix.event.order.approved``
    * ``pretix.event.order.denied``
    * ``pretix.event.orders.waitinglist.added``
    * ``pretix.event.orders.waitinglist.changed``
    * ``pretix.event.orders.waitinglist.deleted``
    * ``pretix.event.orders.waitinglist.voucher_assigned``
    * ``pretix.event.checkin``
    * ``pretix.event.checkin.reverted``
    * ``pretix.event.added``
    * ``pretix.event.changed``
    * ``pretix.event.deleted``
    * ``pretix.subevent.added``
    * ``pretix.subevent.changed``
    * ``pretix.subevent.deleted``
    * ``pretix.event.item.*``
    * ``pretix.event.live.activated``
    * ``pretix.event.live.deactivated``
    * ``pretix.event.testmode.activated``
    * ``pretix.event.testmode.deactivated``
    * ``pretix.customer.created``
    * ``pretix.customer.changed``
    * ``pretix.customer.anonymized``

Installed plugins might register more valid values.


Endpoints
---------

.. http:get:: /api/v1/organizers/(organizer)/webhooks/

   Returns a list of all webhooks within a given organizer.

   **Example request**:

   .. sourcecode:: http

      GET /api/v1/organizers/bigevents/webhooks/ HTTP/1.1
      Host: pretix.eu
      Accept: application/json, text/javascript

   **Example response**:

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Vary: Accept
      Content-Type: application/json

      {
        "count": 1,
        "next": null,
        "previous": null,
        "results": [
          {
            "id": 2,
            "enabled": true,
            "target_url": "https://httpstat.us/200",
            "all_events": false,
            "limit_events": ["democon"],
            "action_types": ["pretix.event.order.modified", "pretix.event.order.changed.*"],
            "comment": null
          }
        ]
      }

   :query integer page: The page number in case of a multi-page result set, default is 1
   :query boolean enabled: Only show webhooks that are or are not enabled
   :param organizer: The ``slug`` field of the organizer to fetch
   :statuscode 200: no error
   :statuscode 401: Authentication failure
   :statuscode 403: The requested organizer does not exist **or** you have no permission to view this resource.

.. http:get:: /api/v1/organizers/(organizer)/webhooks/(id)/

   Returns information on one webhook, identified by its ID.

   **Example request**:

   .. sourcecode:: http

      GET /api/v1/organizers/bigevents/webhooks/1/ HTTP/1.1
      Host: pretix.eu
      Accept: application/json, text/javascript

   **Example response**:

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Vary: Accept
      Content-Type: application/json

      {
        "id": 2,
        "enabled": true,
        "target_url": "https://httpstat.us/200",
        "all_events": false,
        "limit_events": ["democon"],
        "action_types": ["pretix.event.order.modified", "pretix.event.order.changed.*"],
        "comment": null
      }

   :param organizer: The ``slug`` field of the organizer to fetch
   :param id: The ``id`` field of the webhook to fetch
   :statuscode 200: no error
   :statuscode 401: Authentication failure
   :statuscode 403: The requested organizer does not exist **or** you have no permission to view this resource.

.. http:post:: /api/v1/organizers/(organizer)/webhooks/

   Creates a new webhook

   **Example request**:

   .. sourcecode:: http

      POST /api/v1/organizers/bigevents/webhooks/ HTTP/1.1
      Host: pretix.eu
      Accept: application/json, text/javascript
      Content-Type: application/json

      {
        "enabled": true,
        "target_url": "https://httpstat.us/200",
        "all_events": false,
        "limit_events": ["democon"],
        "action_types": ["pretix.event.order.modified", "pretix.event.order.changed.*"],
        "comment": "Called for changes"
      }

   **Example response**:

   .. sourcecode:: http

      HTTP/1.1 201 Created
      Vary: Accept
      Content-Type: application/json

      {
        "id": 3,
        "enabled": true,
        "target_url": "https://httpstat.us/200",
        "all_events": false,
        "limit_events": ["democon"],
        "action_types": ["pretix.event.order.modified", "pretix.event.order.changed.*"],
        "comment": "Called for changes"
      }

   :param organizer: The ``slug`` field of the organizer to create a webhook for
   :statuscode 201: no error
   :statuscode 400: The webhook could not be created due to invalid submitted data.
   :statuscode 401: Authentication failure
   :statuscode 403: The requested organizer does not exist **or** you have no permission to create this resource.

.. http:patch:: /api/v1/organizers/(organizer)/webhooks/(id)/

   Update a webhook. You can also use ``PUT`` instead of ``PATCH``. With ``PUT``, you have to provide all fields of
   the resource, other fields will be reset to default. With ``PATCH``, you only need to provide the fields that you
   want to change.

   You can change all fields of the resource except the ``id`` field.

   **Example request**:

   .. sourcecode:: http

      PATCH /api/v1/organizers/bigevents/webhooks/1/ HTTP/1.1
      Host: pretix.eu
      Accept: application/json, text/javascript
      Content-Type: application/json
      Content-Length: 94

      {
        "enabled": false
      }

   **Example response**:

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Vary: Accept
      Content-Type: application/json

      {
        "id": 1,
        "enabled": false,
        "target_url": "https://httpstat.us/200",
        "all_events": false,
        "limit_events": ["democon"],
        "action_types": ["pretix.event.order.modified", "pretix.event.order.changed.*"],
        "comment": null
      }

   :param organizer: The ``slug`` field of the organizer to modify
   :param id: The ``id`` field of the webhook to modify
   :statuscode 200: no error
   :statuscode 400: The webhook could not be modified due to invalid submitted data
   :statuscode 401: Authentication failure
   :statuscode 403: The requested organizer does not exist **or** you have no permission to change this resource.

.. http:delete:: /api/v1/organizers/(organizer)/webhook/(id)/

   Delete a webhook. Currently, this will not delete but just disable the webhook.

   **Example request**:

   .. sourcecode:: http

      DELETE /api/v1/organizers/bigevents/webhooks/1/ HTTP/1.1
      Host: pretix.eu
      Accept: application/json, text/javascript

   **Example response**:

   .. sourcecode:: http

      HTTP/1.1 204 No Content
      Vary: Accept

   :param organizer: The ``slug`` field of the organizer to modify
   :param id: The ``id`` field of the webhook to delete
   :statuscode 204: no error
   :statuscode 401: Authentication failure
   :statuscode 403: The requested organizer does not exist **or** you have no permission to delete this resource.
