SOAP API Developer's Guide

Clouds with binary code floating aboveCloud with binary code floating above

No Results

Search Tips:

  • Please consider misspellings
  • Try different search keywords
PDF

Newer Version Available

This content describes an older version of this product. View Latest

Setting Up Outbound Messaging

Before you can use outbound messaging, you must set it up via the Salesforce user interface:

Setting Up User Profiles

It is possible to create circular changes with outbound messaging. For example, if a user is performing integrations that trigger workflow, and the workflow actions trigger account updates, those account updates trigger new workflow, and so on. In order to prevent these circular changes, you can disable a user's ability to send outbound messages.

The following is another example of a circular change scenario:
  1. You configure an outbound message to include a sessionId and specify a user in the User to send as field. The user does not have outbound messaging disabled.
  2. A change in a contact record triggers an outbound message from the specified user, with the sessionId to your outbound message listener.
  3. Your outbound message listener calls the Force.com API and updates the same contact record which triggered the outbound message.
  4. The update triggers an outbound message.
  5. Your outbound message listener updates the record.
  6. The update triggers an outbound message.
  7. Your outbound message listener updates the record.

To disable outbound message notifications for a user, deselect “Send Outbound Messages” in the user's Profile. We recommend specifying a single user to respond to outbound messages, and disabling this user's ability to send outbound messages.

Defining Outbound Messaging

To define outbound messages, use this procedure in the Salesforce user interface:

  1. From Setup, click Create | Workflow & Approvals | Outbound Messages.
  2. Click New Outbound Message.
  3. Choose the object that has the information you want included in the outbound message, and click Next.
  4. Configure the outbound message.
    1. Enter a name and description for this outbound message.
    2. Enter an endpoint URL for the recipient of the message. Salesforce sends a SOAP message to this endpoint.

      For security reasons, Salesforce restricts the outbound ports you may specify to one of the following:

      • 80: This port only accepts HTTP connections.
      • 443: This port only accepts HTTPS connections.
      • 1024–66535 (inclusive): These ports accept HTTP or HTTPS connections.
    3. Select the Salesforce user to use when sending the message by specifying a username in the User to send as field. The chosen user controls data visibility for the message that is sent to the endpoint.
    4. Select Include Session ID if you want a sessionId to be included in the outbound message. Include the sessionId in your message if you intend to make API calls back to Salesforce from your listener. The sessionId represents the user defined in the previous step and not the user who triggered the workflow.
    5. Select the fields you want included in the outbound message and click Add.
  5. Click Save, and review the outbound message detail page:
    • The API Version field is automatically generated and set to the current API version when the outbound message was created. This API version is used in API calls back to Salesforce using the enterprise or partner WSDLs. The API Version can only be modified by using the Metadata API.
    • Click the Click for WSDL link to view the WSDL associated with this message.

      The WSDL is bound to the outbound message and contains the instructions about how to reach the endpoint service and what data is sent to it.

If you do not have these options, your organization does not have outbound messaging enabled. Contact salesforce.com to enable outbound messaging for your organization.

Note

Downloading the Salesforce Client Certificate

Your application (endpoint) server's SSL/TLS may be configured to require client certificates (two-way SSL/TLS), in order to validate the identity of the Salesforce server when it takes the role of client to your server. If this is the case, you can download the Salesforce client certificate from the Salesforce application user interface. This is the client certificate that Salesforce sends with each outbound message for authentication.

To download the certificate, use this procedure:
  • From Setup, click Develop | API to display the WSDL Download page.
  • In the WSDL Download page, right-click Download Client Certificate and save it to an appropriate location on your local drive.
  • Import the downloaded certificate into your application server, and configure your application server to request the client certificate. The application server then checks that the certificate used in the SSL/TLS handshake matches the one you downloaded.

Your application (endpoint) server must send any intermediate certificates in the certificate chain, and the certificate chain must be in the correct order. The correct order is:

  1. Server certificate.
  2. Intermediate certificate that signed the server certificate if the server certificate was not signed directly by a root certificate.
  3. Intermediate certificate that signed the certificate in step 2.
  4. Any remaining intermediate certificates. Do not include the root certificate authority certificate. The root certificate is not sent by your server. Salesforce already has its own list of trusted certificates on file, and a certificate in the chain must be signed by one of those root certificate authority certificates.

Note

Viewing Outbound Messages

To view existing outbound messages, from Setup, click Create | Workflow & Approvals | Outbound Messages in the Salesforce user interface.

  • Click New Outbound Message to define a new outbound message.
  • Click View Message Delivery Status to track the status of an outbound message.
  • Select an existing outbound message to view details about it or view workflow rules and approval processes that use it.
  • Click Edit to make changes to an existing outbound message.
  • Click Del to delete an outbound message.

Tracking Outbound Message Status

To track the status of an outbound message, from Setup, click Monitoring | Outbound Messages in the Salesforce user interface. Alternatively, from Setup, click Create | Workflow & Approvals | Outbound Messages, and then click View Message Delivery Status. From this page you can perform several tasks:
  • View the status of your outbound messages including the total number of attempted deliveries
  • View the action that triggered the outbound message by clicking any workflow or approval process action ID.
  • Click Retry to change the Next Attempt date to now. This causes the message delivery to be immediately retried.
  • Click Del to permanently remove the outbound message from the queue.