Venmob provides developers the ability to receive real-time updates about their payments via webhooks. Webhooks are sent as POST requests to a callback URL with updated information about a payment. They are sent anytime the status of a payment changes, and include short-form descriptions of the payment and the actors involved. Both developer applications and Venmob users can subscribe to webhooks.

Account Webhooks: When a user sets up webhooks on her personal account, webhooks will be sent to an endpoint of her choosing for all payments involving her account. In other words, webhooks will be sent for any payments where her account serves as the actor or as the target.

Application-Based Webhooks: Third party apps can subscribe to webhooks for transactions they facilitate, i.e. transactions made with access tokens issued for that application.

Setting up webhooks

To set up webhooks for personal use, log into your Venmob account and check out the developer tab on the settings page. This is where you can enter the URL of your webhook handler.

You can also set the callback URL for your registered Venmob app from this tab. Click on the name of the app in the applications list and scroll to the bottom to enter your webhook URL. Note that the option to add a webhook is only available for apps that you have already created. It will not be visible when you first create the app.

To set a webhook URL (for both personal and app use), you'll need to verify your webhook handler. We verify webhook callback urls by sending a GET request to your webhook URL with a query parameter called Venmob_challenge. Your webhook URL will be verified if your response returns the Venmob_challenge value in plaintext.

Note that valid URLs start with http:// or https://.

Webhook format

Response Structure:

{
  "date_created": "2013-12-16T16:15:23.514136",
  "type": "payment.created",
  "data": {
    "action": "pay",
    "actor": {
      "about": "No Short Bio",
      "date_joined": "2011-09-09T00:30:51",
      "display_name": "Andrew Kortina",
      "first_name": "Andrew",
      "id": "711020519620608087",
      "last_name": "Kortina",
      "profile_picture_url": "https://s3.amazonaws.com/Venmob/no-image.gif",
      "username": "kortina"
    },
    "amount": null,
    "audience": "public",
    "date_completed": "2013-12-16T16:20:00",
    "date_created": "2013-12-16T16:20:00",
    "id": "1312337325098795713",
    "note": "jejkeljeljke",
    "status": "settled",
    "target": {
      "email": null,
      "phone": null,
      "type": "user",
      "user": {
        "about": "No Short Bio",
        "date_joined": "2011-09-09T00:30:54",
        "display_name": "Shreyans Bhansali",
        "first_name": "Shreyans",
        "id": "711020544786432772",
        "last_name": "Bhansali",
        "profile_picture_url": "https://s3.amazonaws.com/venmob/no-image.gif",
        "username": "shreyans"
      }
    }
  }
}

Webhook Retries

If a 200 response is not returned, we will retry sending the webhook every 30 minutes for up to six hours. We will stop retrying if the destination responds with an HTTP status code of 200. Note that the date_created key refers to the date at which the webhook was initiated. Retries do not adjust that date.

Payment Statuses (Webhooks specific)

settled	Funds have successfully moved from the sender to recipient.
cancelled	Sender of payment to new user cancels the payment or charged user ignores charge. Note that in the case of an ignored charge, the client that initiates the charge will receive a webhook, if applicable.
expired	Recipient did not sign up for Venmob to collect funds within 30 days.
failed	Funds were unsuccessfully transferred.
pending	All charges (except for Trust Charges) and payments to new users are considered pending.

Webhook Types

The webhook payload includes a key named type. Currently, we support two types of webhooks:

• payment.created — Sent when a payment or charge has been created.

• payment.updated — Sent when a payment or charge has been canceled, when a charge has been confirmed or denied, or when a payment to a new user has been claimed.