API

Webhooks

Webhooks enable Groove to post data to your server whenever an event has happened. Webhooks can be thought of as event listeners of push notifications.

Webhooks can also be configured through the Groove user interface.

Creating a webhook

POST https://api.groovehq.com/v1/webhooks

Parameters

Name Type Required Options Notes
event string Yes ticket_started, ticket_opened, ticket_closed, ticket_assigned, ticket_priority_changed, ticket_deleted, ticket_tagged, ticket_moved, customer_replied, customer_added, agent_invited, agent_archived, note_added, agent_replied The event to receive notifications about
url string Yes The URL for notifications to be posted to

Example Response

Status: 201 Created

{
  "webhook": {
    "event": "ticket_started",
    "url": "https://www.mysite.com/mywebhook_url",
    "state": "active"
  }
}

Deleting a webhook

DELETE https://api.groovehq.com/v1/webhooks/:id

Example Response

Status: 204 No Content

Payloads

Ticket

{
    "assigned_group": null,
    "assignee": "matt@groovehq.com",
    "created_at": "2012-07-17T13:41:01Z",
    "number": 1,
    "priority": null,
    "resolution_time": null,
    "title": null,
    "updated_at":"2012-07-17T13:41:01Z",
    "href": "https://api.groovehq.com/v1/tickets/1",
    "closed_by": "matt@groovehq.com",
    "links": {
        "assignee": {
            "href": "https://api.groovehq.com/v1/agents/matt@groovehq.com"
        },
        "customer": {
            "href": "https://api.groovehq.com/v1/customers/test@test.com"
        },
        "state": {
            "href": "https://api.groovehq.com/v1/tickets/1/state"
        },
        "messages": {
            "href": "https://api.groovehq.com/v1/tickets/1/messages"
        }
    }
}

Customer

{
  "href": "https://api.groovehq.com/v1/customers/:customer_email",
  "links": {
    "tickets": {
      "href": "https://api.groovehq.com/v1/tickets?customer=:customer_email"
    }
  },
  "email": "smith@gmail.com",
  "first_name": "John",
  "last_name": "Smith",
  "about": null,
  "twitter_username": null,
  "title": null,
  "company_name": null,
  "phone_number": null,
  "location": null,
  "website_url": null,
  "linkedin_username": null,
  "custom": { }
}

Message

{
  "created_at": "2012-07-17T13:41:01Z",
  "updated_at": "2012-07-17T13:41:01Z",
  "note": false,
  "body": "Hey, can I add another item to my order?",
  "href": "https://api.groovehq.com/v1/messages/:id",
  "links": {
    "author": {
      "href": "https://api.groovehq.com/v1/customers/:customer_email"
    },
    "ticket": {
      "href": "https://api.groovehq.com/v1/tickets/:ticket_number"
    }
  }
}

Agent

{
  "email": "matt@groovehq.com",
  "first_name": "Matthew",
  "last_name": "Beedle",
  "href": "https://api.groovehq.com/v1/agents/matt@groovehq.com",
  "links": {
    "tickets": {
      "href": "https://api.groovehq.com/v1/tickets?assignee=matt%40groovehq.com"
    }
  }
}