Skip to main content
Webhooks allow you to receive notifications of events that occurred on the platform. These notifications are delivered to an HTTPS endpoint of your choice.

​
Setup

Multiple webhook URLs per instance are supported. Webhooks can be configured by administrators by heading to Settings -> Manage Integrations -> Webhook subscriptions. For each subscription, it’s possible to listen to the events for all merchant accounts in an instance, or to the events for one merchant account.

​
Authentication

Each subscription can authenticate its webhook requests to your endpoint in one of the following ways.
  • Basic authentication: Gr4vy sends the username and password in the Authorization header.
  • OAuth: Gr4vy requests an access token from your token URL with the password grant or the client credentials grant. It sends the grant_type, client_id, client_secret, and, for the password grant, the username and password, plus the scope if you set one, as form parameters in the body of the token request, with the Content-Type set to application/x-www-form-urlencoded. It doesn’t send them in an Authorization header. Gr4vy then sends the access token as a bearer token in the Authorization header of each webhook request.
Gr4vy reuses an access token for up to one hour. If your endpoint responds with a 4XX status, Gr4vy discards the token and requests a new one for the next attempt. Webhook subscriptions don’t support custom request headers. To verify that a request comes from Gr4vy, use signatures.

​
Webhook delivery behavior

  1. Multiple subscriptions
    If you configure multiple subscriptions pointing to different URLs, each subscription receives its own webhook deliveries.
  2. Retries are subscription-specific
    If a webhook delivery fails, it is only retried for the subscription that encountered the failure, even if other subscriptions (pointing to the same or different URLs) succeed.

​
Supported features

  • Multiple webhook subscriptions per merchant account
  • Merchant account and instance-level webhook subscriptions
  • Detailed payloads for transactions, payment methods, buyers, billing details, and most other transaction related events.
  • Over 20 different webhook events.
  • Basic authentication credentials (username/password)
  • OAuth authentication (password and credentials grant)
  • Automatic retries of undelivered events
  • Webhook signatures to verify authenticity.

​
Next steps