Webhooks

Rexpense has a notification system using webhooks that allows you to receive notifications on a pre-specified endpoint (a URL under your system) whenever an event concerning expenses occurs. When it happens, Rexpense will send an HTTP POST request with the payload content (as JSON) in the body of the request.

A webhook is related to an organization. So, all expense events (changes) related tothat organizaton will be trigger a webhook request.

Remember that your endpoint should be available and respond to the webhook request with a 200 Ok HTTP response. If you respond with anything else (or if we receive no response at all), Rexpense will try to send the request again for up to 5 times before giving up.

The possible events are:

Event Description
expense_created when expense is created
expense_updated when expense is updated
expense_updated_status when expense status is updated
attachment_created when attachment is created
attachment_updated when attachment is updated
attachment_destroyed when attachment is destroyed
comment_created when comment is created
comment_updated when comment is updated
comment_destroyed when comment is destroyed

Example Webhook

    {
      "id": 1,
      "url": "http://mysystem.com/webhooks/rexpense",
      "description": "My description endpoint",
      "_links": [
        {
          "rel": "self"
          "method": "GET",
          "href": "https://app.rexpense.com/api/v1/organizations/1/integrations/webhooks/1"
        },
        {
          "rel": "update"
          "method": "PUT",
          "href": "https://app.rexpense.com/api/v1/organizations/1/integrations/webhooks/1"
        },
        {
          "rel": "destroy"
          "method": "DELETE",
          "href": "https://app.rexpense.com/api/v1/organizations/1/integrations/webhooks/1"
        }
      ]
    }

Payload

When an event is fired, the webhook sends payload to the given URL in a HTTP POST request with two specifics headers:

X-Rexpense-RequestId

This header is unique for each request and is used to calculate the X-Rexpense-Signature.

X-Rexpense-Signature

This header is the signature of the webhook. It is calculated based on the secret field defined on webhook creation. Its value can be found with the HMAC hex digest of the body of the payload added with the X-Rexpense-RequestId in its beginning, using the webhook secret as the key.

Example Webhook Payload

POST /payload-url

X-Rexpense-RequestId: d12c56319826262a371989930be7d0b2
X-Rexpense-Signature: b09209a810d67b382193680a0342896c2cb042a8
Content-Type: application/json
    
    {
      "event": "comment_created",
      "created_at":"2014-10-10T15:19:54Z",
      "expense": {
        "id": 8,
        "_links": {
          "rel":"self",
          "method":"GET",
          "url":"https://app.rexpense.com/api/v1/expenses/8"
        }
      },
      "event_source": {
        "id": 25,
        "type": "Comment",
        "_links": {
          "rel":"self",
          "method":"GET",
          "url":"https://app.rexpense.com/api/v1/expenses/8/comments/25"
        }
      }
    }

List webhooks

List all webhooks of an organization.

Definition

GET https://app.rexpense.com/api/v1/organizations/:organization_id/integrations/webhooks

Example Request

$ curl -u $YOUR_API_TOKEN:X -X GET https://app.rexpense.com/api/v1/organizations/1/integrations/webhooks \
      -H 'Accept: application/json' \
      -H 'Content-type: application/json'

Response Example Success

HTTP 200 OK
    {
      "count": 2,
      "webhooks":
      [
        {
          "id": 1,
          "url": "http://mysystem.com/webhooks/rexpense",
          "description": "My description endpoint",
          ...
        },
        {
          "id": 2,
          "url": "http://mysystem.com/second-webhooks/rexpense",
          "description": "My second description endpoint",
          ...
        }
      ]
    }

Show a webhook

This endpoint shows webhook information for the organization.

Definition

GET https://app.rexpense.com/api/v1/organizations/:organization_id/integrations/webhooks/:id

Example Request

$ curl -u $YOUR_API_TOKEN:X -X GET https://app.rexpense.com/api/v1/organizations/1/integrations/webhooks/2 \
      -H 'Accept: application/json' \
      -H 'Content-type: application/json'

Response Example Success

HTTP 200 OK
    {
      "id": 2,
      "url": "http://mysystem.com/webhooks/rexpense",
      "description": "My description endpoint",
      ...
    }

Response Example Failure

HTTP 404 Not Found
    {
      "errors": {
        "message": "Resource not Found."
      }
    }

Create a webhook

This endpoint registers a webhook for the organization.

url: string required
description: string
secret: string

Definition

POST https://app.rexpense.com/api/v1/organizations/:organization_id/integrations/webhooks

Example Request

$ curl -u $YOUR_API_TOKEN:X -X POST https://app.rexpense.com/api/v1/organizations/1/integrations/webhooks \
      -H 'Accept: application/json' \
      -H 'Content-type: application/json'
      -d '{"url":"http://rexpense.com", "description":"My description"}'

Response Example Success

HTTP 201 OK
    {
      "id": 1,
      "url": "http://mysystem.com/webhooks/rexpense",
      "description":"My description",
      "secret":"my-secret-token",
      ...
    }

Response Example Failure

HTTP 422 Unprocessable Entity
    {
      "errors": {
        "url": ["is invalid"]
      }
    }

Update a webhook

Updates an existing webhook.

description: string
secret: string

It's not possible to update Webhook URL in order to prevent any error when requesting it and sending the payload. If you'd like to change it, you'll have to delete the existing one and create a new one.

Definition

PUT https://app.rexpense.com/api/v1/organizations/:organization_id/integrations/webhooks/:id

Example Request

$ curl -u $YOUR_API_TOKEN:X -X PUT https://app.rexpense.com/api/v1/organizations/1/integrations/webhooks/2 \
      -H 'Accept: application/json' \
      -H 'Content-type: application/json'
      -d '{"url":"http://rexpense.com","description":"My updated description"}'

Response Example Success

HTTP 200 OK
    {
      "id": 2,
      "url": "http://rexpense.com",
      "description":"My updated description",
      "secret":"my-secret-token",
      ...
    }

Response Example Failure

HTTP 422 Unprocessable Entity
    {
      "errors": {
        "url": ["is invalid"]
      }
    }

Destroy a webhook

Destroys an existing webhook.

id: integer required

Definition

DELETE https://app.rexpense.com/api/v1/organizations/:organization_id/integrations/webhooks/:id

Example Request

$ curl -u $YOUR_API_TOKEN:X -X DELETE https://app.rexpense.com/api/v1/organizations/1/integrations/webhooks/2 \
      -H 'Accept: application/json' \
      -H 'Content-type: application/json'
    
Response Example Success

    
HTTP 204 No Content