Skip to main content

 Services

Web services from /about to /webhooks

webhooks

/clients/{client}/webhooks [POST]

Description

Create a new webhook for an OAuth client.

Use the internal client id, not the client ID in the URL. For example: /clients/123/webhooks.json

Parameters

NameDescriptionRequiredTypeDefault
eventsComma-separated list of events to filter (empty means all, .* suffix can be used)nostring
formatThe output format xml or jsonnostringxml
groupsComma-separated list of groups to filter events (in addition to projects, empty projects & groups means all)nostring
insecuresslIf the SSL certificate for the URL is verifiednobooleanfalse
nameThe webhook name, optional stringnostring
objectThe objects’ format in the output (minimal: public/private IDs only orbasic)nostringminimal
projectsComma-separated list of projects to filter events (empty projects & groups means all)nostring
serverIf the server events are includednobooleanfalse
urlThe webhook URL stringyesurl

Permission

This service requires administrator.

Response

A successful response returns the <webhook> element wrapped in a <webhook-creation> element.

<webhook-creation>
  <webhook id=""
           created=""
           modified=""
           url=""
           server="[true|false]"
           [name=""]
           [activatesecret=""]
           [projects=""]
           [groups=""]
           [events=""]
           object="[minimal|basic]"
           format="[xml|json]"
           insecuressl="[true|false]"
           status="[pending|active|disabled|warning|error|unreachable]">
    <client ...>
      <member ...> ... </member>
    </client>
  </webhook>
</webhook-creation>
 

Sample XML

<webhook-creation>
  <webhook id="789" 
           created="2019-05-07T12:04:59+10:00"
           modified="2019-05-07T12:04:59+10:00" 
           url="https://ps.example.org/"
           server="false"
           object="minimal"
           format="xml"
           insecuressl="true"
           status="pending"
           name="Test"
           events="comment.*,group.*">
    <client id="123" 
            identifier="4739db31320c67c5" 
            requires-consent="false"
            confidential="false"
            name="sample"
            grant-type="password"
            created="2018-03-19T14:18:16+11:00"
            modified="2019-02-01T18:18:16+11:00"
            last-token="2022-07-06T17:00:00+10:00"
            description="Sample app"
            client-uri="https://app.example.org/"
            access-token-max-age="21600"
            refresh-token-max-age="2592000">
      <member id="456" status="activated"
              firstname="Joan" surname="Snow" username="jsnow">
        <fullname>Joan Snow</fullname>
      </member>
    </client>
  </webhook>
</webhook-creation>

Sample JSON

{
  "webhook": {
    "id": 789,
    "created": "2019-05-07T12:04:59+10:00",
    "modified": "2019-05-07T12:04:59+10:00",
    "url": "https://ps.example.org/",
    "server": false,
    "object": "minimal",
    "format": "xml",
    "insecuressl": true,
    "status": "pending",
    "name": "Test",
    "events": "comment.*,group.*",
    "client": {
      "id": 123,
      "identifier": "4739db31320c67c5",
      "requiresConsent": false,
      "confidential": false,
      "name": "Sample",
      "grantType": "password",
      "created": "2018-03-19T14:18:16+11:00",
      "modified": "2019-02-01T18:18:16+11:00",
      "lastToken": "2022-07-06T17:00:00+10:00",
      "description": "Sample app",
      "clientUri": "https://app.example.org/",
      "accessTokenMaxAge": 21600,
      "refreshTokenMaxAge": 2592000,
      "member": {
        "id": 456,
        "firstname": "Joan",
        "surname": "Snow",
        "username": "jsnow",
        "status": "activated",
        "fullname": "Joan Snow"
      }
    }
  }
}

Error Handling

CodeError condition
0x1701If the client is invalid
0x1702If the name is already in use
0x1703If the URL is invalid
0x1704if the object parameter is not valid
0x1705if the format parameter is not valid
0x1706If one of the projects is invalid
0x1707If one of the groups is invalid
0x1708If one of the events is invalid
Created on , last edited on